How to write a tutorial: the ultimate guide

Home  >>  Blog  >>  How to write a tutorial: the ultimate guide

How to write a tutorial: the ultimate guide

On March 14, 2017, Posted by , in Blog, With No Comments

People look to tutorials to solve problems, and it’s no accident that as the front door to all the information about everything, the internet has literally billions of tutorials of one sort or another.  (Seriously.  Google “how to” and you’ll get “About 3,060,000,000 results”.) So standing out isn’t easy. Fortunately for you, while no one sets out to write a bad tutorial, those three billion ‘how to’ webpages don’t all solve problems equally well, and creating good tutorial content is something you can learn.

Creating a bad how to is a double disservice: not only are you failing to help your intended audience; you’re defeating the tutorial’s purpose. Instead of making the audience more comfortable with your chosen topic, you’ve made them more frustrated. And if the idea was to show them you’re an expert, you just did the exact opposite.

This tutorial is for people who are interested in crafting tutorials and how to content in any medium. It requires no special skills or resources other than a desire to produce better content.

When you create good content, it’s easy to stand out.  We’re going to do a deep dive into how to write a tutorial in this article.
The process basically involves 6 steps:

  1. Define your goals
  2. Define your audience
  3. Define your topic and your example
  4. Break down the topic into steps (or smaller concepts)
  5. Create the actual tutorial
  6. Promote the tutorial

Let’s take each of these steps in turn.

Define your goals

Tutorials and how tos have an especially big impact when you use them to unlock the value of solving problems, whether you’re offering highly technical products in a B2B market or creating YouTube videos to build an audience. The important thing is to know what it is you’re trying to accomplish.

There are three types of goals you need to consider when you’re thinking about your tutorial: business goals, marketing goals and content goals. Business goals are directly tied to revenue, such as “make a million dollars this year,” or “create 50 new customers.”  Marketing goals are how you plan to achieve that, such as “build a mailing list of 25000 subscribers,” or “get 5,000 new social media followers.”

Of course, your tutorial isn’t going to do these things for you directly; every single person who reads your tutorial isn’t going to follow you on Facebook.  Some will, of course, so the popularity of your content is important; you measure that popularity through metrics such as web traffic, comments, and social shares.

The percentage of people who read your tutorial and then take the action you want them to take (follow you, opt in to your mailing list, call you on the phone, etc.) is called the conversion rate, and there are various ways to improve it.

The important thing, though, is that if you know approximately what your conversion rate is, you can work your way backwards from your business goals to your marketing goals to your target metrics.

Content goals involve what it is you need to accomplish with the actual tutorial itself. When defining your content goals, you generally need to consider the following five questions:

What do people need to know in order to:

  • Understand that they have a problem you can solve?
  • Understand that what you have can solve their problem?
  • Make use of your solution to solve their problem?

Note that you don’t necessarily have to be selling something for these questions to matter; if you were creating a tutorial on how to change your oil for your car club website, your audience would first have to understand that the knocking sound from their engine is because they haven’t changed the oil in 10,000 miles (1). Then they’d have to understand that you can show them how to change their oil themselves rather than taking it into the shop (2). Finally, they’d need to know how to do the actual oil change (3).

You’d also need to consider the question of “what do you want them to do after they go through your tutorial?” You always want them to take some sort of action; it could be as simple as bookmarking your page or subscribing to your channel, or as complicated as making an appointment to see a demo. The important thing is to know what action you want them to take, so that you can gear your content toward getting them to take it.

Basically, you need to be able to answer the question: why are you doing this?

Define your audience

Now that you know why you’re creating this tutorial, you need to define the audience.  Who are you creating this content for?

Don’t say “everybody”.

Look, if you focus on everything, you’re focusing on nothing. You need to be focusing on a specific individual so that you can make sure you’re meeting their needs.  That (hopefully) doesn’t mean that only that person will get value from what you’re doing, but you need to start somewhere. For example, this tutorial is aimed at engineers who want to write technical articles, but someone creating a YouTube makeup tutorial will still get value from it.

In defining your audience, you’re going to create a persona. Personas define information about a user, such as their job, their goals, and their values. It helps you understand:

  • What is important to the audience
  • What they’re likely to respond to
  • How to make your content most effective
  • How to reach them

Perhaps the most important thing you need to know about them, though, is their pain point.

What stands in their way? Introducing pain points

Pain points are more than just problems; they’re obstacles that keep your audience from getting what they want. If there were no pain points in the world, we wouldn’t need to create anything.

This starts pretty simple: we want to be warm and dry, but it’s cold and raining, so we need clothing and shelter. In this case, the pain point is that it’s cold and raining, and the solution is clothing and shelter.

It gets as complicated as we need it to be: we want to cut down on our Amazon Web Services bill, but our developers need instant self-service access to computing resources to do do their job, so we need an in-house private cloud solution. In this case, the pain point — the thing that’s stopping us from cutting our AWS bill — is our developers’ need for resources. The solution is private cloud.

Sometimes the solution isn’t a thing so much as a skill — and that’s where you and your tutorials come in.  

You, yourself, have a pain point that brings you to this tutorial on tutorials.  You wanted to create better tutorials, but you weren’t sure how.

painpoints

You thought that there was a better place to be — but a pain point stopped you from getting there. Now, as a result of your investing time and effort, you can get to that better place.

Prerequisites

There are two types of prerequisites you need to consider: what your audience needs to know, and what they need to have.

You need to determine what skills your audience has to have in order to benefit from the the tutorial, and you need to let them know up front, so that they don’t waste their time and get frustrated if they don’t meet that minimum standard. It’s better to send them off to learn more and ask them to come back than to lose them forever because they get frustrated — or worse, feel stupid.

Similarly, you need to be sure to specify, right up front, any technical or physical resources they’re going to need.  For example, this tutorial doesn’t require anything but your brain, but if I were writing a tutorial on, say, a Software Defined Networking solution, there are certain hardware and software requirements the audience needs in order to make use of it.

Again, put these right up front, and if possible, make it easy for the audience to fill in any gaps by linking to resources where they can find what they need.

One gotcha: you should assume that you know more than your audience. This doesn’t make them stupid; it just means that not everything that is obvious to you is obvious to them. The trick is in determining how much more you know. If the gap is too big, and you find yourself laying out too much before your audience can get to work, you might want to see if you’ve selected an audience that is too broad. This example is probably too broad:

  • “For those unfamiliar with the role of fire in cooking, bear in mind that heat represents the difference in temperature created by the release of molecular energy as a result of a variety of chemical reactions. ”  

Conversely, this example is probably too narrow:

  • “Before you begin, activate the Large Hadron Collider.”

There’s no hard-and-fast answer to that gap; you’ll have to think whether the gap is something that the user can satisfactorily narrow as a result of reading your tutorial.

Define your topic

Now that you know who you’re talking to and why, it’s time to figure out what you’re going to tell them.

In some cases, you already know; it was the idea that came first, and now you’re trying to figure out how to execute it. In other cases, though, you’re trying to provide a service of some sort to your audience, and you’re looking for ideas.

In this case, you need to keep in mind that the purpose of your tutorial is very simple.  You need to educate and entertain them, yes, but the most important thing you need to do is move them closer to their goal.

Remember that all content, even when it’s non-fiction such as tutorials, is about storytelling. Don’t, however, fall into the trap of thinking that you are the hero, rescuing the audience from some dragon with your knowledge or solution. No, the audience is the hero, the problem is the villain, and you’re the mentor helping them get to their goal.

Coming up with ideas

The first place to look for ideas is to get into your audience’s heads. What are they interested in? When you were developing the persona, you generated a ton of information about where they put their attention, such as websites, books, magazines, and people they follow; now’s the time to look at those sources to see what’s being talked about, and more importantly, what questions are being asked. Forums and question-and-answer sites such as StackExchange are perfect places to find questions that are stumping people. What topics come up regularly?

Once you’ve got a following, coming up with ideas for tutorials is as simple as asking your audience what they’d like to see. You can do this in a number of ways, from participating in groups on Facebook and LinkedIn to soliciting comments on social platforms or on your website, to sending an email or hosting a survey.

The importance of the right example

Virtually every tutorial needs an example to give context to what you’re talking about. For example, if you’re writing a tutorial about an animation program, obviously you’ll want the reader to animate something. If you’re filming a YouTube video about how to plant tomatoes, you’re going to actually go ahead and plant some tomatoes.

Sometimes, though, it’s not so cut and dried.

For example, say you’re creating a tutorial about Javascript in general, and about mouse movements in particular. What’s your example?

Well, the most obvious is to have the audience create a page that shows the coordinates of the mouse at any given time.  OK, that’s fine.

But you want to be more than fine.

What about creating a game where they have to click on a moving object? Now you’re not just teaching them, you’re creating a) something memorable, b) something fun, and c) something that teaches them not just what to do, but why you might want to do it — in other words, something that gives them a more durable learning experience.

When you’re coming up with examples, ask yourself two questions:

  1. Why would anybody ever need this? and
  2. What is the most fun anybody could have with this?

Try to come up with an example that is just complex enough to demonstrate all of the concepts you’re trying to explain — and no more complex than that.

Structure your tutorial

OK, finally, we’re ready to start building the tutorial. I know it seems like we’ve done a lot of work to get here, and we have; but you’ll find that if you plan properly, the actual tutorial construction is the easy part.

The first step is to make sure that you have all of the information that you need. If this is a topic on which you’re not an expert, that means research, and/or interviewing Subject Matter Experts (SMEs) in the topic.

Working with Subject Matter Experts

Dealing with SMEs can be a touchy issue; most of the time they’re extremely busy, so you’ll want to make sure that you make the most effective use of their time.  To do that, you’ll want to keep a few things in mind:

  • Do your research first:  Come in having at least a basic idea of what you need to know. Doing at least the basic research shows the SME that you’re respectful of their time; this is especially important when it comes to introductory information that’s easily accessible on the internet.  Save your questions for the things that truly need an expert to explain them.
  • Work around their schedule, not yours: You want your SMEs to feel like they have the time to give you all the support you need, not like you’re sneaking in between meetings. Those side-trips where they go off on a tangent can be much more valuable than you suspect, both because they give you additional context that you can use, and because they might spark additional ideas for content.  Besides, you want them to be willing to deal with you again, both in reviewing this tutorial and potentially when creating additional pieces.  Remember, they’re doing you a favor.
  • Make sure you understand what you’re being told:  Restate what the SME tells you in your own words so that you’re sure that you understand it, and if you don’t, you give him or her the opportunity to correct you.
  • Take careful notes, and record the interview if possible:  Even with the most meticulous note-taking, chances are you’re going to have additional questions when you get down to creating the actual tutorial. It’s much easier when you know that it wasn’t already answered in your original discussions.
  • Have the SME review the finished product:  It’s always good to have an expert review the final product.  If you’re not the expert, the person you interviewed is the perfect choice, and if you’re referencing them as the expert, you should consider it mandatory.

In the end, chances are that your relationship with your SMEs is mutual; you need them to create a good tutorial, but the tutorial that you’re creating is to their advantage. Try to work as a team as much as possible.

Breaking up the topic

There are two ways to break up the content of a tutorial and they depend on whether you’re doing a “How to” or a “What is” type of tutorial.

A “How to” tutorial is exactly what it sounds like; a series of concrete steps that tell you how to get from point A to point B, usually with the opportunity for the audience to follow along.  In a situation like this, you’ll want to break the topic down into its component steps.

A “What is” tutorial gives you information about the topic, but rather than concentrating on concrete steps, it focuses on concepts that may build on each other.  For example, you might write an article that explains what the various parts of an atom are and how they work together. Obviously this isn’t something that the audience can easily try for themselves (static electricity experiments and Large Hadron Collider owners aside). In this situation, you’ll break the topic down into concepts.

Sometimes you’ll have a tutorial that’s a hybrid of the two. For example, you might intend to teach the concepts, and create concrete steps that demonstrate those concepts, such as rolling a ball down a flight of steps to help the audience better understand kinetic and potential energy.  

Alternatively, you might have a tutorial that teaches the steps at a higher level, but is intended to focus on the concepts. For example, this tutorial that you’re reading now is broken down into basic steps (“Define your goals”, “Define your topic”, etc.) but doesn’t have the audience follow along and do each step themselves.

Create the outline

Once you know how you’re going to break up the topic, it’s time to put together an outline of what you think you’re going to write. It’s entirely possible (and even probable) that where you end up won’t be what you started with.  And that’s OK.  As the saying goes, the act of planning is more valuable than the plan itself.

This is because putting things into an outline forces you to really look at the structure and make sure that it works before you start writing. You’ll also find there’s another benefit to a detailed outline: by thinking about structure separate from style, you won’t just create better structure, you’ll create it faster.

And once you start writing (or creating, if you’re using another medium), you’ll find that a detailed outline takes out all the uncertainty and makes things flow because you’re not having to constantly stop to make decisions.

Creating the actual tutorial

Now you’re ready to actually create the tutorial. You should have your outline in hand. If you’re creating a programming tutorial, you should already have all of the code you’re going to show; if you’re doing a screencast, you should at least know what you’re going to do. If you’re filming a video, you should have all of your materials handy, as well as a general idea of what you want to say.

Your tutorial will generally have three parts.

The introduction (or “Should I be here?”)

Start by introducing the problem and the solution to set the scene for your tutorial. In journalism, this is called the “nutgraf” — the paragraph that gives you the “nut” of the article. For example, the nutgraf in this tutorial (actually two paragraphs) is:

People look to tutorials to solve problems, and it’s no accident that as the front door to all the information about everything, the internet has literally billions of tutorials of one sort or another.  (Seriously.  Google “how to” and you’ll get “About 3,060,000,000 results”.)

Standing out isn’t easy. Of course, no one sets out to write a bad tutorial, those three billion ‘how to’ webpages don’t all solve problems equally well. Fortunately for you, creating good tutorial content is something you can learn.

Immediately, the audience knows whether this is a problem that resonates with them. You also, however, want to let them know whether they’re part of the audience to which the tutorial applies.  In this case that is:

This tutorial is for people who are interested in crafting tutorials and how to content in any medium. It requires no special skills or resources other than a desire to produce better content.

Close the introduction with a quick recap of what’s ahead, either in paragraph or bullet form. Giving your audience an idea of where the tutorial is going to go both provides is a helpful way to confirm for them that they should be here and provides context for what they’re learning as they go through the material.

The body (“What should I do?”)

In the body of the tutorial, you’ll go through each step and thoroughly explain it.

Remember that your audience doesn’t know what you know. You need to provide context and reasons for everything that you do so that they can understand not just what you’re doing, but why. This way, if they get lost at some point, they’ll be able to find their way back.  When in doubt, overexplain; nobody will ever complain that you explained something too well.

Use visuals as much as possible. This might involve photos, or it might involve simply showing the result of a command; either way, remember that a large percentage of your audience will be made up of visual learners, so give them a visual representation of what you’re doing. Also, make sure to explain the visuals; it may be obvious to you what’s going on in that diagram, but not to anyone else.

When you’re finished writing, be certain to test your tutorial, especially if you changed direction part way through. And be certain to really start from scratch. For example, if you’re demonstrating a web how to with any kind of sign-in, make sure to use an incognito tab so that you know how the application will behave for your visitors, who wouldn’t be logged in to any existing systems.

The conclusion (“What did I do?”)

Unless the tutorial is very short, you will want to end up with a summary that briefly reiterates what you’ve covered. Now that the user has gone through the entire process, earlier steps that may not have seemed to make any sense will have fallen into place, and this is a good time for them to be able to see the big picture.

Finally, it’s always good to provide the user with additional resources where they can get more information. This may be in the form of specifications you’ve referenced, links to deeper materials or training classes, or books that give a more in-depth look at the topic.

Revisit the Introduction

The process of writing a tutorial is often the best way of finding out whether the intended goals of the tutorial have been met. In other words, don’t be surprised if in finishing the tutorial, you don’t end at exactly the place you intended to be.

Be sure to revisit the nutgraf and the conclusion. As you write more tutorials, this will come naturally. But the process of writing out the process with a workable example exposes many unstated assumptions. Often, it’s useful to see which of those newly exposed assumptions the reader should know before they begin.

Promotion

Once you’re done with the tutorial and it’s been published, you’re still not finished. Even if you’ve published a sparkling how-to that makes people sit up and take notice and brands you as a Super Genius, none of that matters unless people actually consume your content. And remember, you’re competing with 3 billion other how to articles; you’ll need to at least prime the pump to get yours out there.

You can use several methods to get traffic to to your content:

  • Social: Today social media is generally the first line of defense when it comes to promoting your content; articles are posted to Facebook, LinkedIn, Twitter, and so on.  Where you post should be determined by where you’re audience is. Most extremely technical users are on LinkedIn, so that’s a good choice — especially if you belong to groups where the posting would be appropriate, and most of all welcome.  Also, Twitter is the network where people most look to find content to read elsewhere, as opposed to Facebook, where users are, in general, looking for content to consume on the platform.
  • RSS: RSS used to be cool; virtually every site had it and there were plenty of people consuming content through RSS readers rather than coming to the actual site. RSS is no longer cool, but that doesn’t mean that you can ignore it; RSS is used for syndication, which can display your content on other sites (if you’re OK with that).
  • Email:  If you have an email list, sending a notice of your new content can be incredibly effective. These are people who already know you and are included to trust you and your judgement, so they’re likely to check out a link that you send them.
  • Repurposing content: You should never, ever have just a single piece of content. You always take that content and transform it into other pieces, whether that’s a video screencast version of a tutorial, a transcript of a video, or even a series of tweets that point back to the original.  Even if your content can’t link back to the original, you want to take advantage of the availability cascade by being seen in multiple places.
  • SEO: The Grand Old Man of traffic, Search Engine Optimization seems less important that it used to be, but you’ll still benefit from good SEO practices.  After all, you’re trying to stand out from those other 3 billion tutorials, remember?
  • Outreach: It may be a big place, but the internet is still made up of people. Reach out to other bloggers, podcasters, and influencers on social media to help spread your content. And remember that it’s a two-way street. Don’t expect other people to link to you if you don’t link to anyone else. 
  • Paid traffic: Even if you have a big audience, it’s almost always good to prime the pump to let them know your content exists. From there, they can share it, but if they never find it in the first place, it will just languish, not doing anyone any good.

So what did we learn?

The tutorial space is jam-packed, but that’s only because both demand and usefulness are so high. By learning how to create better tutorials, you provide a better service to your target audience and you get better results, no matter your goals.

Creating a good tutorial involves 6 basic steps:

  1. Define your goals: Make sure you know both what you want to teach your audience, and why they’d want to learn it from you.
  2. Define your audience: Make sure you know who you’re talking to, and what their interests and concerns are.
  3. Define your topic and your example: Pick a topic that is both useful and interesting to your target audience, and that fulfills your goals.
  4. Break down the topic into steps (or smaller concepts): Some tutorials are better suited to concrete steps, others to concepts that build on each other, and still others are a combination of the two. Figure out what serves your topic best and break it down into the smallest possible chunks for your audience.
  5. Create the actual tutorial: Be clear, be concise, and most of all, don’t be boring. And make absolutely certain that you’ve tested everything thoroughly.
  6. Promote the tutorial: The best how to article in the world is useless if nobody consumes it. Make sure you send it out into the world properly.

If you’re interested in creating tutorials, join us on February 2 for a live web class on all aspects of building quality how to and tutorial content.

Resources

Leave a Reply

Your email address will not be published. Required fields are marked *

css.php