How To

Summary

How Tos are steps to perform a key goal or task.

Example


Schema

  • 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?

Last edited Apr 29, 2010 at 7:22 PM by mycodeplexuser, version 33

Comments

No comments yet.