How to Get Tutorials and How-To Articles Right

Tutorials and how-to articles are step-by-step content that teaches readers to complete a specific task: set up an account, configure a feature, fix an error, build a thing. They are among the most practical pieces a company publishes, and among the most unforgiving. A good tutorial solves a real problem and builds trust, because the reader finishes with something working. An untested or unclear one frustrates readers at exactly the moment they needed help, and they remember whose instructions let them down.

This article is a troubleshooting manual for tutorials that are not doing their job. It is written for content leads, technical writers, product marketers, support teams and subject experts who write instructions as part of their day. Instead of a general theory of instructional writing, it is organized by symptom: the signs that a tutorial is failing, how to recognize each one, the usual causes, the fix and how to prevent it from happening again.

Most tutorial problems trace back to a short list of good practices that were skipped: state the goal and prerequisites, write one action per step, show expected results, include screenshots where they help and test the tutorial end to end. If you only take one habit from this manual, make it the last one.

How to diagnose a failing tutorial

Tutorials fail quietly. Readers rarely write in to say that step 7 was ambiguous; they close the tab, open a support ticket or try a competitor's documentation. So diagnosis starts with the evidence you already have: support tickets that reference the tutorial, comments under the article, on-page feedback widgets, scroll depth and exit points in analytics, and search queries that land on the page. Then read the tutorial yourself, cold, and try to follow it.

The table below summarizes the symptoms covered in this manual. Use it to find the section that matches what you are seeing.

Two of these symptoms, untested steps and outdated screenshots, deserve particular attention because they produce instructions that are confidently wrong. The others make tutorials harder to follow; those two can make them impossible to complete.

Symptom: readers stall before the first step

How to recognize it

Readers arrive, scroll a little and leave. Support tickets ask questions like "Which plan do I need for this?" or "Where do I find the API key?" that the tutorial never answered. Comments ask whether the tutorial applies to the reader's version, operating system or account type. In analytics, exits cluster near the top of the page.

Likely causes

The tutorial starts with step 1 without saying what the reader will achieve or what they need before starting. Prerequisites should be listed before the steps, and when they are missing, readers either do not know whether the tutorial is for them or discover halfway through that they lack something they needed at the start: a permission, a plan level, an installed tool, a piece of information from another system.

The fix

Add two short elements above the steps. First, a goal statement in one or two sentences that says what the reader will have when they finish, for example: "By the end of this tutorial, your online store will send an automatic confirmation email when an order ships." Second, a prerequisites list that covers everything the reader needs before step 1:

• Access: the account type, role or permission required.
• Software and versions: tools that must be installed, and the versions the tutorial was tested with.
• Information: keys, IDs, file paths or credentials the reader needs to have to hand.
• Prior tasks: anything that must already be set up, linked to its own tutorial.
• Time: a realistic estimate of how long the task takes, if you have tested it.

Keep the prerequisites to things the reader genuinely needs. A list of twelve items where eight are obvious buries the four that matter.

Symptom: "this doesn't work" comments and tickets

How to recognize it

Comments or tickets report that the reader followed the steps and got an error, a blank screen or a different result. Several readers report failing at the same step. Internal staff defend the tutorial ("it works for me"), which is itself a clue: it works for people who already know the product.

Likely causes

There are two, and they often appear together. The first is untested instructions: the tutorial was written from memory, from a specification or from a developer's notes, and nobody followed it exactly, step by step, before publishing. The second is skipping steps experts take for granted. Experts perform some actions so automatically that they no longer notice them: saving a file before running it, refreshing a page, switching to the right workspace, clearing a cache, confirming an email, waiting for a process to finish. They leave those steps out, and a newcomer fails at exactly that point.

The fix

Test the tutorial end to end, and test it properly. Steps should be followed exactly before publishing, which means literally doing what each step says and nothing else. That rule matters: if you do something the step does not say, because you know it is needed, you have found a missing step.

The observed test with a non-expert is the step teams most often skip, and it is the one that catches the steps experts take for granted. The writer cannot see those gaps, by definition. If the tutorial supports a product, record which product version it was tested against so you know when to test again.

Symptom: readers lose their place in the steps

How to recognize it

Readers report doing something twice or missing an action. Support tickets describe a half-configured result. In usability sessions, readers scroll back up repeatedly, and when they switch between the tutorial and the product, they cannot find where they left off.

Likely causes

Steps are written as paragraphs of prose, or each numbered step packs three or four actions into one sentence: "Open Settings, select Notifications, turn on Email alerts and choose Daily from the frequency menu, then save." A reader who performs the first two actions and switches back to the tutorial has to reread the whole step to find where they were.

The fix

Use numbered steps for tasks that must be done in order, and write one action per step, which keeps instructions clear. Numbered lists tell the reader that sequence matters and give them a way to keep their place. Both the Google developer documentation style guide and the Microsoft Writing Style Guide treat procedures as a distinct pattern built on numbered steps, and they are worth reading in full if you write instructions regularly.

A few further conventions make steps easier to follow:

• Start each step with the action. "Select Save" is faster to scan than "Now you will want to make sure you save."
• Put the location or condition first when it matters. "In the Billing section, select Update card" tells the reader where to look before what to do.
• Match the interface exactly. Use the button and menu labels as they appear on screen, formatted consistently, usually in bold.
• Separate optional steps clearly. Mark them as optional at the start, not at the end.
• Keep explanations short and after the action. If a step needs a paragraph of explanation, the explanation probably belongs above the steps.

Long procedures benefit from grouping. If a task genuinely takes 25 steps, break it into three or four stages with their own headings, each with its own short numbered list. The principles behind this are covered in more depth in our guide to getting content chunking right.

Symptom: readers are not sure whether it worked

How to recognize it

Readers finish the tutorial and then ask, in comments or tickets, "Is it supposed to look like this?" or "How do I know it's working?" Some repeat steps unnecessarily because they saw no confirmation. Others proceed confidently from a failed step and only discover the problem several steps later, when it is much harder to trace.

Likely causes

The tutorial describes actions but not results. The writer knows what success looks like, so they never wrote it down.

The fix

Show expected results. After any step that produces a visible change, and always at the end, tell the reader what they should see: a confirmation message, a new item in a list, a status that changes from Pending to Active, a line of output in a terminal. Where possible, quote the exact text of the message. Then, for the most likely failures, say what the reader will see instead and what to do about it.

A good pattern for a key step looks like this in practice:

1. Select Send test email.
2. Check the inbox for the address you entered in step 4. A message with the subject line you set should arrive within a few minutes.
3. If no message arrives, check the spam folder, then confirm that the sender address shows Verified in Settings.

The final expected result deserves its own short section: what the finished state looks like, how to check it, and what the reader can do next. That last part is where a tutorial can link onward to the natural next task, which is a more useful call to action than a generic sign-up prompt. Our article on writing calls to action covers how to make that next step specific.

Symptom: screenshots that do not match the screen

How to recognize it

Readers say they cannot find a button that appears in the screenshot. Comments point out that the menu has moved or been renamed. The screenshots show an old logo, an old color scheme or a layout the product no longer uses. Readers compare the screenshot with their screen, conclude they are in the wrong place and give up.

Likely causes

Outdated screenshots are one of the most common tutorial mistakes because interfaces change more often than documentation is reviewed. A product team ships a redesign or renames a menu item, and every tutorial that shows the old screen becomes misleading overnight. The more screenshots a tutorial has, the faster it goes out of date.

The fix

Include screenshots where helpful, not everywhere. A screenshot earns its place when the reader needs to find something visually, such as an unlabeled icon, a crowded settings page or a result they need to recognize. It does not earn its place when the text already says "Select Save" and the Save button is obvious.

• Write steps that work without the images. The text should be complete on its own, so a missing or outdated image does not break the tutorial and readers using screen readers get the full instructions.
• Crop tightly. Show the relevant part of the screen, not the whole browser window. Smaller crops go out of date less often because they include less of the interface.
• Annotate sparingly. A single outline or arrow pointing at the relevant control is enough.
• Write useful alt text. Describe what the image shows and why it matters to the step.
• Keep source files. Store screenshots with names that map to the tutorial and step, so replacing them is quick.

For more on choosing, cropping and captioning images, see how to get images and captions in articles right.

Symptom: a tutorial that sprawls

How to recognize it

The tutorial is very long, and analytics show readers jumping to the middle rather than reading from the top. The title promises one thing, but the page covers several. Readers comment that they only needed part of it. Updating it is painful because a change to any one task means editing a long, interconnected page.

Likely causes

Several tasks have been mixed into one tutorial. It usually happens with good intentions: the writer wanted to be thorough, or a tutorial grew over time as people added "while you are here, you might also..." sections. The result is a page where readers who want task B have to wade through task A, and readers who want task A are distracted by tasks B and C.

The fix

One tutorial, one task. Test each section by asking whether a reader could reasonably want to do it on its own. If so, it is a separate tutorial. Split the page, give each new tutorial its own goal, prerequisites and expected result, and link them in sequence where one depends on another: the prerequisites of the second tutorial can link to the first.

A long series is fine, as long as each part is a complete task. The distinction is between a series of focused tutorials that together build something larger and a single page that tries to do everything at once. If the sprawl is really reference material (every setting explained, every option listed), it belongs in a help center article or reference page rather than a tutorial. Our guide to writing help center articles covers how the two formats work together.

Symptom: the right readers never find it

How to recognize it

The tutorial is good, but traffic is low, or the search queries that bring readers in are only loosely related to the task. Support staff keep sending the link manually because people cannot find it themselves. Readers arrive, realize the page is about something else and leave.

Likely causes

The title and introduction describe the task in the company's vocabulary rather than the reader's. A tutorial called "Configuring outbound notification workflows" will not be found by someone searching for how to send an email when an order ships. Clever or vague titles make this worse.

The fix

Name the task in the title in the words readers use. "How to" titles work for tutorials because they match how people phrase the problem. Include the product or tool name where it helps readers confirm they are in the right place. Look at the search queries in your analytics, support ticket wording and questions in community forums to learn the reader's vocabulary. Our article on headline writing covers the wider principles.

Inside the article, the goal statement should repeat the task in plain words, and the headings for stages should describe what each stage achieves. Categorize tutorials consistently too, so readers browsing the site can find a group of related tasks rather than one isolated page.

Symptom: the tutorial was right once and is wrong now

How to recognize it

The tutorial passed testing when it was published, but newer comments report problems. The steps refer to features that have changed. The prerequisites mention versions that are no longer supported. Nobody on the team is sure who is responsible for it.

Likely causes

Tutorials describe a moving target. Products, interfaces, third-party services and even operating systems change, and a tutorial with no owner and no review schedule decays. This is the long-term version of the untested instructions problem: instructions that were tested once but have not been tested since the thing they describe changed.

The fix

Give every tutorial a named owner and a review trigger. Reviews should happen on a fixed cycle and whenever the product changes in a way that affects the task. Show readers when the tutorial was last reviewed or updated, and be honest about what changed; our guide to publication and update dates explains how to do that without misleading anyone. When a reader reports an error, fix it promptly, and if the error could have caused harm (lost data, a security setting left open), say so clearly in the article. Our article on corrections and editorial policies covers when and how to note corrections.

Reader comments are a valuable early-warning system for tutorials, because readers are testing your instructions every day on current versions of the product. Make it easy for them to report problems, and route those reports to the tutorial's owner. Our practical guide to comments and community on articles covers how to moderate and respond to them.

A worked example: repairing a tutorial that generates tickets

The numbers in this example are illustrative, chosen to show how the fixes fit together rather than to describe any real company.

Imagine a software company with a tutorial called "Integrations setup." Support tags show about 40 tickets a month that reference it. The page is roughly 3,000 words long and covers connecting three different third-party tools. It has 22 screenshots, 9 of which show an interface that was redesigned last spring. Steps are numbered, but many contain three or four actions each.

The team works through the symptoms in order:

1. Diagnose. Reading the 40 tickets shows that about half fail at the same point: readers do not have admin rights, which the tutorial never mentioned. Another quarter fail because a step assumes the reader has already created an API key. The rest are scattered.
2. Split. The single page becomes three tutorials, one per integration, each about 900 to 1,200 words, each with its own goal, prerequisites and expected result. A short overview page links the three.
3. Add prerequisites. Each tutorial now lists admin access, the plan level required and the API key as prerequisites, with a link to a separate tutorial on creating API keys.
4. One action per step. The original 18 crowded steps become about 30 single-action steps across the three tutorials, grouped into stages.
5. Expected results. Each tutorial now shows the confirmation message after connecting and a check at the end.
6. Screenshots. 22 screenshots become 10, all current and tightly cropped, used only where the interface is hard to navigate.
7. Test. Two people from the sales team, who have never set up an integration, follow each tutorial in a clean test account while a writer watches. They find two more missing steps, which are added before publication.

In this illustrative case, the measure of success is the monthly count of tickets that reference the integration tutorials, tracked for the next three months, together with on-page feedback and the proportion of readers who reach the final section. If the ticket count falls meaningfully and the remaining tickets are about genuinely unusual situations, the repair worked. If one tutorial still generates most of the tickets, it goes back for another observed test.

Preventing tutorial problems before they reach readers

Every fix in this manual is easier to apply before publication than after. The checklist below turns them into a pre-publication review. It is short enough to use on every tutorial, and it catches most of the symptoms above.

Build the fixes into a template

The most reliable prevention is a tutorial template that makes the right structure the default. When the page skeleton already contains a goal statement, a prerequisites list, numbered stages, an expected result section and a "what to do next" link, writers fill in the blanks rather than remembering the rules. A template also makes reviews faster, because an editor can see at a glance which section is empty or thin. Keep the template short: a heading for each element and one line of guidance under each is enough. Anything longer tends to be deleted rather than followed.

Pair the template with a simple record for each tutorial: the owner, the product version it was tested against, the date of the last end-to-end test, the list of screens it shows and the date of the next review. A spreadsheet is fine. What matters is that when the product team announces a change, someone can find every affected tutorial in minutes rather than waiting for readers to report problems in the comments.

Write the tutorial for the reader you actually have. If your audience includes people who are less confident with technology, give them extra context about where things are on screen, avoid jargon and use larger, clearer screenshots; our guide to content for older audiences has more on this. If your audience is developers, they will still need prerequisites and expected results, but they will want less explanation between steps.

When to bring in help with tutorials and how-to articles

Many teams write good tutorials in-house, especially when a subject expert and an editor work together and the test step is taken seriously. The point at which outside help pays off is when tutorials support product adoption: when the rate at which customers successfully set up and use your product depends on your instructions, and the volume of tutorials, the pace of product change or the cost of support tickets has outgrown what the team can maintain.

At that point, the work is less about writing individual articles and more about the system around them: templates that build in the goal, prerequisites and expected results; a testing routine that happens on every release; a screenshot inventory; ownership and review schedules; and a structure that helps readers move from one task to the next. That is the kind of work our content strategy team does.

Where this comes from

• Google for Developers — Google developer documentation style guide
• Microsoft Learn — Microsoft Writing Style Guide

The figures and practices above come from the sources listed.

Working on something like this?

We take on Content Strategy work for teams who want it done once, properly. Tell us what you are building and we will tell you honestly whether we are the right studio for it. Start a project.

Where to go next

• Writing Calls to Action: What Actually Works
• How to Get Writing for Translation Right