Writing Prescriptive Guidelines
These are some practices we learned in the guidance business to write more effective guidelines:
- Follow the What To Do, Why and How Pattern
- Keep it brief and to the point
- Start with Principle Based Recommendations
- Provide Context For Recommendations
- Make the Guidelines Actionable
- Consider Cold vs. Warm Handoffs
- Create Thread Killers
Follow the What to Do, Why and How Pattern
Start with the action to take -- the "what to do". This should be pinned against a context. Context includes which technologies and situations the guidance applies. Be sure to address "why" as well, which exposes the rationale. Rationale is key for the developer audience. It's easy to find many guidelines, missing context or rationale. Some of the worst guidelines leave you wondering what to actually do.
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 actionable? Often the answer is no. It's hard to do, but it keeps the content "lean and mean".
Start with 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. An example principle-based recommendation would be: Validate Input for Length, Range, Format, and Type. You can then build more specific guidelines for a technology or scenario from this baseline recommendation.
Provide Context for Recommendations
Avoid blanket recommendations. Recommendations should have enough context to be prescriptive. Sometimes this can be as simple as prefixing your guideline with an "if" condition.
Make the Guidelines Actionable
Be prescriptive, 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.
Choose Warm vs. Cold Handoffs
If you are sending the reader to another link for a specific piece of information, be explicit. It's as simple as adding "For more information on xyz, see ..." before your link. That's a warm hand off. A cold hand off is simply having a list of links and expecting the reader to follow the links and figure out why you sent them there. The worst is when the links are irrelevant and you simply added links because you could.
Create Thread Killers
A "thread killer" is a great piece of information that when quoted or referred to can stop a technical discussion or alias question (a discussion thread) 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 guidance that nails the problem. A great endorsement is when your "thread killer" is used to address FAQs on discussion aliases and forums.
Where to See This in Practice
The following are examples of prescriptive guidelines based on these practices: