Guidelines for Writing Guidelines

Guidelines for writing solid recommendations:
  • Follow the What To Do, Why and How Pattern
  • Keep it brief and to the point
  • Use Principle Based Recommendations
  • Provide Context For Recommendations
  • Make the Guidelines Actionable
  • Use Must and Should Appropriately
  • Consider Cold vs. Warm Handoffs
  • Create Thread Killers

Follow the What to Do, Why and How Pattern

When you write a recommendation, provide context by addressing when to follow the recommendation or guideline. Be sure to address why as well, which exposes the rationale. Rationale is key for the developer audience.

Keep It Brief and to the Point

Avoid "blah, blah, blah". Say what needs to be said as succinctly as possible. Ask "why, why, why?" to everything you write - every paragraph and every sentence. Does it add value? Does it help the reader? Is it really necessary. Often the answer is no. It's hard to do, but keep the content "lean amd mean".

Use Principle-Based Recommendations

A good principle-based recommendation addresses the question: "What are you trying to accomplish?". Expose guidance based on engineering versus implementation or technology of the day. This makes the guidance less volatile and arguably more useful.
Correct
Encrypt Sensitive Data

Incorrect
Use SSL to Encrypt Sensitive Data

Use SSL to Encrypt Sensitive Data is a potentially poor recommendation because it focuses on the implementation instead of the principle or what you are trying to accomplish.

Provide Context for Recommendations

Avoid blanket recommendations. Recommendations should have enough context to be prescriptive. The following are examples of recommendations that don't provide context:
Correct
Use SSL when encryption between server and client is required

Incorrect
Always use SSL

Make the Guidelines Actionable

Be drescriptive, not descriptive. The guideline should be around actionable vs. just interesting information. Note that considerations are actions provided you tell the reader what to consider, when and why. As a general rule, avoid providing too much background or conceptual information. Point off to primer articles, books etc for background. If conceptual information is required options include:
  • Using an Appendix
  • Including the concepts early in the chapter, but in a way that relates well to the tasks that the reader is supposed to be able to accomplish.

Use Must and Should Appropriately

Should is appropriate for most recommendations or guidelines. Do not use must unless it's an absolute requirement.

Consider Cold vs. Warm Handoffs

When the readers read a statement, do you expect the reader to have some knowledge of the area that you are talking about so he can figure out the details if you provide him direction – Cold Handoff, or do you expect the reader to be a novice and require detailed steps – Warm Handoff.
If you are using the 'Cold Handoff' strategy, follow these two guidelines:
  • Expose this thinking (that you expect them to figure the "How to do it part") in sections such as "How to use this chapter" etc.
  • Provide pointers so they can go do it (if you are not covering it in your chapter.) For example point to Microsoft Knowledge Base or MSDN articles.

Create Thread Killers

A thread killer is a page/document (or section of a page/document) that when quoted or referred to can stop a technical discussion or alias question with no further comments. Look at the alias, understand the questions being asked, and tackle the root causes and underlying problems that cause these questions. (Think of the questions as symptoms). Make documents that tackle the principles. If your docs get forwarded to FAQs on aliases all pending comment should in the ‘thanks!’ form.
Also make sure to use an appropriate "eye catching" header - to make it very easy to reference the page and the relevant section on the page.

Last edited May 2, 2009 at 3:42 AM by mycodeplexuser, version 1

Comments

No comments yet.