Software Engineering, Project Management, and Effectiveness
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.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:
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:
For a list of guidance module types, templates, and examples see Templates for Writing Guidance at http://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:
Examples of Guidance Modules
J.D. Meier posted some guidance on authoring prescriptive guidance modules for Guidance Explorer : How
One of the questions I get is how we build and publish our guides and what's the relationship of CodePlex
I thought it might be helpful to walk through a deliverable so you can see my current approach for building