Return to HomePage

---

Template

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

---

Template Explained

* Title
* Applies To -
* Insert the most direct technologies, or application types this guideline applies to. Unlike technology field above, this section can contain a combination of items Make a simple list. Don’t be verbose.
* What to Do - Insert the specific action for the user to take. Express an explicit user action: design, implementation or configuration action. Leverage “do” and “do not” verbage (e.g. Do Not Create Threads on a Per-Request Basis) If context or condition is important preface with "If …" …. (e.g. If you call COM components, consider calling ReleaseComObject) Don’t include how to or implementation. That belongs in the How To section. Don’t include why information in this section. That belongs in the Why section.
* Why - Insert why this guideline is important. This should motivate you to take action.
* When - Insert when this guideline is relevant here.
* How - Insert the steps required to apply this guideline
* Problem Example - Insert problem example
* Solution Example - Insert solution example
* Additional Resources - Add links to additional resources here.
* Related Items - Add information about related guideline or checklist items here

---

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?

---

Return to HomePage