Return to HomePage

---

Template

* Title
* Applies To
* Summary
* Contents
* Objectives
* Overview
* Summary of Steps
* Step <<N>>.
* Considerations <<Name>>
* Additional Resources
* Related Items

---

Test Cases

Title
* Does the title distinguish by product or version where possible?
* Are important nouns a user might scan for towards the left of the title?
Applies To
* Is it clear what technologies or products this applies to?
* Conversely, is it clear what technologies of products this does not apply to?
Summary
* 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?

Contents
* Is each major heading listed?
Objectives
* 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?

Overview
* 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?
Step <<N>>
* 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?

Considerations <<Name>>
* 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?

Additional Resources
* 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?

Related Items
* 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?

---

Return to HomePage