Guidelines

Summary

Present the "what to do", "why", and "how"

Example

Schema

  • Title
  • Applies To
  • What to Do
  • Why
  • When
  • How
  • Problem Example
  • Solution Example
  • Related Items

Test Cases

Title
  • Does the title clearly state the action to take?
  • Does the title start with an action word (eg. Do something, Avoid something)?

Applies To
  • Do you list technology and version? (e.g. ASP.NET 2.0)

What to Do
  • Do you state the action to take?
  • Do you avoid stating more than the action to take?

Why
  • Do you provide enough information for the user to make a decision?
  • Do you state the negative consequences of not following this guideline?


When
  • Do you state when the guideline is applicable?
  • Do you state when not to use this guideline?


How
  • Do you state enough information to take action?
  • Do you provide explicit steps that are repeatable?


Problem Example
  • Do you show a real world example of the problem from experience?
  • If there are variations of the problem, do you show the most common?
  • If this is an implementation guideline, do you show code?

Solution Example
  • Does the example show the resulting solution if the problem example is fixed?
  • If this is a design guideline is the example illustrated with images and text?
  • If this is an implementation guideline is the example in code?

Additional Resources
  • Are the links from trusted sites?
  • Are the links correct in context of the guideline?

Related Items
  • Are the correct items linked in the context of the guideline?


Additional Tests to Consider When Writing a Guideline
  • Does the title clearly state the action to take?
  • Does the title start with an action word (eg. Do something, Avoid something)?
  • 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 7, 2010 at 11:09 PM by paulenfield, version 4

Comments

No comments yet.