Guidelines Template

  • Article

Sometimes the guidelines in our guidance such as Improving Web Application Security, Improving .NET Application Performance and .NET 2.0 Security Guidance are missing some of the important details such as when, why or how.  To correct that, we've created a template that explicitly captures the details.  We use this template in Guidance Explorer.  I'll also be posting .NET Framework 2.0 performance examples that use this new template.

Guideline Template

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

Test Cases

The test cases are simply questions we use to help improve the guidance.  The guidelines author can use the test cases to check that they are putting the right information into the template.  Reviewers use the test cases as a check against the content to make sure it's useful. 

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

  • Versions are clear?
     

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?