The how-to article

A how-to article is a set of steps that describe how to accomplish one particular goal.

Here are some best practices for writing a how-to:

  • Try to mention when and why your user might want to perform the task. It's not always obvious to the reader, even when it's obvious to you.

  • Before listing the steps in a process, list the prerequisites. This might include permissions, if the task is for admins only. Users might also need to know about size limits and formats when uploading materials.

  • Use numbered steps and describe the process in the most logical order, using relatively few steps. If you have 10 or more steps, ask yourself whether you are describing more than one task.

  • Give users one way to complete a task, rather than describe every way. When you suggest two paths, you're asking users to think through both of them and choose. Save your readers' time and effort by eliminating one of the options.

  • Provide only the information necessary to complete each step. Don't add reference or concept information that users might or might not need. If it exists elsewhere, you can provide a link.

  • Walk through the task as you write the instructions. You'll invariably recall details you might otherwise have left out.

  • Find a test driver. Invite someone to test drive your how-to article instructions from start to finish, preferably someone who needs help to complete the task, but who is capable of the individual steps. Your how-to article needs this test drive so you can uncover omitted steps, incorrect details, steps out of order, and information gaps that block users. There will be gaps, because you know things about the product that your user doesn't know, and it's difficult to adjust for that.

Guidelines that apply to each step

  • Close to the beginning, make sure the user knows the purpose of the step. For example, maybe I need a piece of data from the response in step one in order to complete a request in step 2. People prefer to know why each step is necessary.

  • Use code examples. For REST API documentation, this means that you use codeblocks to demonstrate the request and the expected response for every step.

  • Try to create examples that are nearly ready to use by cut-and-paste. (Your readers may have to plug in authorization tokens, user IDs, and other individual data.)

  • Follow each example with extensive comments that explain how it works. Some users get started by playing with the example code and they'll get frustrated if they cannot make it work. For them, the example should be followed by notes like these:

    • The parts of the code they need to replace with their own authentication keys and user IDs.

    • Warnings about common errors that will prevent the request from working.

    • Notes about the purpose or usage of any request properties or response properties that are unique to this endpoint.