KB Tutorial Template
Titles begin with an action verb describing what the user needs to do. We write for international audiences, so titles never include gerunds. We avoid the "How to …" format because it makes titles hard to scan in search results.
- Yes: Import Subscribers to a List
- No: Importing Subscribers to a List
The intro summarizes the material to be covered and specifies where in the app the tasks take place. For some users, the introduction is all they need to point them in the right direction.
If there are several ways to accomplish a task, each one goes under its own heading. Steps are always presented as numbered lists. Bulleted lists are often used to show several related pieces of information.
Offers another way to accomplish the same task.
In most articles, there are related processes or information that accompany the main tutorial steps. This info is also broken out into its own section, for scannability and to keep the tutorial steps short and easy to follow.
Notes contain info that is not necessary to follow the steps, but is important to consider in the overall process.
We use notes very sparingly to avoid causing banner blindness in readers that can make them overlook important information.
Sometimes a tutorial needs to show more than numbered lists and screenshots. Depending on the content, we may include a table, a code block, or an embedded video.