This is the third in a series of suggested practices for creating knowledge base content.
One of the most frequent types of content in knowledge base articles is procedures, whether to provide general information or to help troubleshoot: once you've described an issue, you often need to tell users how to figure out whether that's the issue they're having, and how to solve it. Providing clear, complete, and accurate steps to reproduce and procedures is a lot harder than it looks! Here are some tips to help.
"A-one and a-two" - Use numbered lists
The best way to present procedures and steps to reproduce is by using numbered lists. Advantages of numbered lists include:
-
Actions in numbered steps are easiest to follow and pick out. Don't make users read a paragraph and have to guess where one action ends and the next action begins.
-
Users should be able to read a step, then do the action, then come back and read the next step. Numbers make it easier to see what they have to do next.
-
Having a numbered step to refer to makes troubleshooting easier.
-
Creating a numbered list often helps you see whether you've left out any required actions.
Tip – Using the numbered list icon (
Steps for Steps
What makes for good steps?
Provide each and every step.
The more familiar you are with the procedure, the more likely you are to accidentally skip steps or not include details because "everyone will know." Be sure to include every step.
Have one action per step.
Combining a lot of actions into a single step can be confusing and harder to go back and forth between doing the actions and reading the instructions.
Put explanations underneath the step.
Make sure users can clearly see the actions they need to do.
QA for STR
Quality checking for steps to reproduce:
Keystroke the steps if you have the time.
Pretend you are a user less familiar with the product area and see whether you've provided all the steps and that they all work.
If the article Audience is set to Public or Customer, make sure the content is appropriate for external viewing.
Make sure the article doesn't include any internal or customer information in the text, URLs, or screenshots, don't use language such as "we" or "I," and that any internal troubleshooting information is in the Internal Notes field.
Include helpful links.
Add product documentation links if they would provide helpful information to users to complete steps. For the link text, use the title of documentation topic rather than the URL. For example:
<a href="http://www.sample.com/docs/Useful-documentation-topic.html" title="Useful documentation topic" rel="nofollow" target="_blank">Useful documentation topic</a>.
More Tips for Authoring Knowledge Base Content
For even more helpful tips for authoring good knowledge base content, see the other posts in this series:
