Software Engineering, Project Management, and Effectiveness
These are some practices we learned in the guidance business to write more effective guidelines:
Follow the What to Do, Why and How PatternStart 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 PointAvoid "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 RecommendationsA 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 RecommendationsAvoid 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 ActionableBe 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 HandoffsIf 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 KillersA "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 PracticeThe following are examples of prescriptive guidelines based on these practices:
J.D. Meier posted some guidance on authoring prescriptive guidance modules for Guidance Explorer : How
Book building is art and science. I've built a few books over the years at patterns & practices.