Note: This article is updated at Agile Content Development.
When I ramp new folks on the team, I find it helpful to whiteboard how I build prescriptive guidance. Here's a rough picture of the process:
I've used the same process for Performance Testing Guidance, Team Development with Visual Studio Team Foundation Server, and WCF Security.
Here's a brief explanation of what happens along the way:
The dominant focus here is identifying candidate problems, candidate solutions, and figuring out key risks, as well as testing paths to explore. The best outcome is a set of scenarios we can execute against.
- Research - finding the right people, the right problems, and the right solutions.
- Prototypes - experiment and test areas of high risk to prove the path. This can include innovating on how we build prescriptive guidance. We also use these to test with customers and get feedback on the approach.
- Question Lists - building organized lists of one-liner user questions.
- Task Lists - building organized lists of one-liner user tasks.
- Scenario Frames - organizing scenarios into meaningful buckets. See Scenario Frame Example.
- Information Models - framing out the problem space and creating useful ways to organize, share, and act on the information. See Web Services Security Frame.
- Guidance Types - testing which guidance types to use (how tos, checklists, guidelines, patterns, ... etc.)
The dominant focus here is product results. It's scenario-driven. Each week we pick scenarios to execute against.
- Development - building prescriptive guidance, including coding, testing, and writing.
- Backlog - our backlog is a prioritized set of scenarios and guidance modules.
- Iterations - picking sets of scenarios to focus development on and test against.
- Refactoring - tuning and pruning the guidance to improve effectiveness. This includes breaking the content up and rewriting it. For example, a common refactoring is factoring reference information from action. We try to keep reference information in our Explained modules and action information in our How Tos.
- Testing - step through the guidance against the scenario. The first pass is about making sure it works. It should be executable by a human. Next, it's about reducing friction and making sure the guidance really hits the what, why and how. We test the guidance against objectives and scenarios with acceptance criteria so we know when we're done.
- Problem Repros - creating step by step examples that reproduce a given problem.
- Solution Repros - creating step by step examples that reproduce a given solution.
We produce a Knowledge Base (KB) of guidance modules and a guide. The guidance modules are modular and can be reused. The guide includes chapters in addition to the guidance modules. Here's examples from our WCF Security Guide:
We release our guidance modules along the way to test reactions, get feedback and reshape the approach as needed.
- CodePlex - we publish our guidance modules to CodePlex so we can share early versions of the guidance and get customer feedback, as well as to test the structure of the guidance, and experiment with user experience.
- Guidance Explorer - we publish guidance modules to Guidance Explorer so users can do their own guidance mash ups and build their own personalized guides. Our field also uses this to build customized sets of guidance for customers.
Once we've tested and vetted the guidance and have made it through a few rounds of customer feedback, we push the guidance to MSDN.
- MSDN - this is the trusted site that users expect to see our prescriptive guidance in final form.
- Visual Studio/ Visual Studio Team System - once we're a part of the MSDN distribution, we can automatically take advantage of the VS/VSTS documentation integration.
My Related Posts