How Tos are steps to perform a key goal or task.
- Applies To
- Summary of Steps
- Step <<N>>.
- Considerations <<Name>>
- Additional Resources
- Related Items
- Does the title distinguish by product or version where possible?
- Are important nouns a user might scan for towards the left of the title?
- Is it clear what technologies or products this applies to?
- Conversely, is it clear what technologies of products this does not apply to?
- Does the summary include key points extracted from the guidance?
- Does the summary give quick insight into what the how to is doing?
- Does the summary articulate the proposed solution?
- Does the summary pass the ‘hallway test’ – would this be your verbal description of the solution?
- Is each major heading listed?
- Are the most important learnings from the document extracted into the objectives?
- Is each objective expressed as a specific task?
- Is the objectives list short enough that it can be easily scanned and understood?
- Does the overview provide enough background information to understand why it is necessary to take the steps?
- Does the overview provide enough information that the module can stand alone?
Summary of Steps
- Will the set of steps listed solve the problem?
- Does each step explain what to do, why it is important and then how to take action?
- If there is a decision point is it called out with an explicit ‘if…’ condition?
- Is the How To capable of standing alone without requiring the user to search elsewhere to complete the solution?
- Where appropriate, are there code or configuration file examples?
- Are the consequences of applying this How To considered?
- Are potential solutions to these consequences outlined?
- Has testing, security, performance, reliability and operations been considered?
- For each link, do you know why the link is included without first following the link?
- Are the links from trusted sites?
- Are the links correct in context of the How to?
- Are the correct items linked in context of the How to?
Additional Tests to Consider When Writing a How To
- Does the title effectively convey what the how to is addressing?
- If the item is a MUST, meaning it is prevelant and high impact, is Priority = p1?
- If the item is a SHOULD, meaning it has less impact or is only applicable in narrower circumstances, is Priority = p2?
- If the item is a COULD, meaning it is nice to know about but isn't highly prevelant or impactful, is Priority = p3?
- If this item will have cascading impact on application design, is Type = Design?
- If this item should be followed just before deployment, is concerned with configuration details or runtime behavior, is Type = Deployment?
- If this item is still in progress or not fully reviewed, is Status = Beta?