How To articles take the reader through a series of steps required to solve a specific problem. They explain in detail how to do a specific task. Use How To articles to prescribe a set of sequential steps readers must do to be able to use a feature. Don't use How To articles to teach concepts.
How To articles are often confused with tutorials. How To articles are problem-oriented, while tutorials are learning-oriented.
Readers that have experience with the product and need a specific question answered use How To articles. New users who want to solve a problem instantly can also benefit, provided the How To is well-written and states any prerequisite knowledge required to complete the task.
Summarize what the reader will achieve by reading the explanation article:
- Are you writing for developers or for managers?
- Are you writing for people who have a certain problem to solve?
- Are you writing for a particular industry or market segment?
Readers should already have read a concept about the topic in an About article. Ensure you link to the relevant About article in the overview.
This section prevents readers from getting halfway through and discovering that they need to go and read other documentation before they can continue. Prerequisites can include other articles or information to read, or it can be technical dependencies such as requiring an internet connection, or particular software.
Describe what the audience needs to know, or needs to have, before they attempt the How To. By stating the requirements up-front, you prevent your readers from having a bad experience with your How To. You can include links to procedures or information, or give useful pointers about how to get what they need.
For example:
Before you begin, make sure you meet these prerequisites:
* API credentials for the v3.5 API. For more information about accessing your API credentials, see http://example.com/access_your_api_credentials.
* Access to the Postman application.
* A conceptual understanding about RESTful APIs. For more information, see http://example.com/restful_apis.
* (Optional) A development environment (IDE) that displays API responses formatted for readability.
* A list of favorites prepared, so you can manage them. For more information about favorites lists, see http://example.com/favorite_lists.
When you are explaining steps in a process, it can be useful to include screenshots for each key part of the process. This can help readers orientate themselves as they move through the steps. It can also help someone who is evaluating the software see how it works without having to install it.
This section contains a table, which allows you to add a screenshot or call out next to each step. You can also use an ordered list structure without screenshots in markdown, with HTML tables.
It's likely that during the course of explaining a multi-step process you will touch on other topics related to the current one, but not strictly required. A "See also" section at the end is useful to provide the reader with suggestions on further reading without interrupting the topic covered by the current document. The distinction between this section and "Before you start" (as outlined above) is that the content in that section is necessary to the current topic, while the reader should be able to complete the How-to without reading the topics in this section. An example might be setting up an email client, which requires working credentials to an active email address. The reader need not know how to install and run his/her own email server in order to acquire that access, although this is potentially useful. The link to documentation on running a local mail server could therefore be included in the "See also" section.
-
Example 1.
-
Example 2.