Some of the most important information for customers is how to do things. This information is often called a task or procedure, and it needs to be structured consistently so it is easy to follow and to understand.
Tasks also need to be tightly scoped to accomplish a single specific user objective. If needed, create additional tasks to accomplish other objectives, even if many of the steps are shared (employ content reuse if possible). Users can more successfully find and follow procedural information that is focused on a single goal than information that is digressive and tries to address many needs at once.
Do: Create a Custom Widget (user goal)
Don't: Using the Widget Editor (UI description)
Prefatory information
The task title, short description, and contextual information should be as brief as possible, but let users know:
- why they would or would not perform the task
- what risks the procedure incurs, if any
- what prerequisites exist, if any
Task titles should preferably use an active present imperative verb identifying the goal of the task.
Steps
Steps in a procedure do not require a lead-in phrase. The presence of numbered steps should identify the steps to be followed, and a lead-in phrase would be redundant to the task title and short description.
- Number steps sequentially using Arabic numbers starting with 1.
- Each step begins with a simple imperative sentence of the form do this with an action verb.
- If needed, provide more information about the step in a new paragraph following the imperative in the step.
- If needed, provide substeps numbered with lowercase English letters starting with a for each step. It's often preferable to provide multiple steps than substeps. Substeps should be explanatory about how to accomplish the step, and might be skipped by experienced users.
- Tightly scope each step to accomplish a single meaningful part of the procedure.
- Where needed, describe the result of an individual step only if it is unexpected or significant. This should be a separate paragraph within the step. Do not describe step results that are obvious or trivial, such as a dialog opening.
Result
If needed, follow the list of steps with information about the outcome of the procedure or next steps to take. As with individual step results, don't state obvious effects but only more meaningful ones.
Troubleshooting
Troubleshooting information can be handled in multiple ways, depending on the need:
- If a problem is likely to occur for a single step, include brief troubleshooting information within the step but after the "happy path."
- If the problem is likely to occur for the procedure as a whole, include brief troubleshooting information within the procedure but after the "happy path" steps.
- If the problem requires more than very brief troubleshooting information, create a separate troubleshooting article and link to it from the procedure.
Troubleshooting information can include advice to contact support.