How To Write Prescriptive Guidance Modules

  • Article

Here's a quick reference for writing guidance modules.  Guidance modules are simply what I call the prescriptive guidance documents we write when creating guides such as Improving Web Application Security, Improving .NET Application Performance and .NET 2.0 Security Guidance.

 How To Write Prescriptive Guidance Modules

Summary of Steps

  • Step 1. Identify and prioritize the tasks and scenarios.
  • Step 2. Identify appropriate content types.
  • Step 3. Create the guidance modules.

Step 1. Identify and prioritize the tasks and scenarios.
Task-based content is "executable".  You can take the actions prescribed in the guidance and produce a result.  Scenarios bound the guidance to a context. This helps for relevancy and for evaluating the appropriateness of the recommendations.

Good candidates for tasks and scenarios include:

  • Problems and pain points
  • Key engineering decisions
  • Difficult tasks
  • Recurring engineering questions
  • Techniques

In many ways, the value of your prescriptive guidance is a measure of the value of the problem multiplied by how many people share the problem.

Step 2. Identify appropriate guidance module types.
Choose the appropriate guidance module type for the job:

  • Guidelines - Use "guidelines" to convey the "what to do" and "why" w/minimal how (how tos do the deep how) ... in a concise way, bound against scenarios/tasks.
  • Checklist Items - Present a verification to perform ("what to check for", "how to check" and "how to fix")
  • How Tos - Use "how tos" to effectively communicate a set of steps to accomplish a task (appeals to the "show me how to get it done")

For a list of guidance module types, templates, and examples see Templates for Writing Guidance at https://www.guidancelibrary.com

Step 3. Create the guidance modules.
Once you've identified the prioritized scenarios, tasks, and guidance types, you create the guidance.   This involves the following:

  • Identify specific objectives for your guidance module.  What will the user's of your guidance module be able to do?
  • Collect and verify your data points and facts.
  • Solve the problem your guidance module addresses.  This includes performing the solution and testing your solution.
  • Document your solution.
  • Checkpoint your solution with some key questions:  when would somebody use this?  why? how?
  • Review your solution with appropriate reviewers.

Examples of Guidance Modules