When I ramp new folks on the team, I find it helpful to whiteboard how I build prescriptive guidance.
Agile Content Life-Cycle
Here’s a rough picture of the process
Examples
I’ve used the same process, leading virtual teams of 15+, for creating he following “Blue Books” for Microsoft:
- Building Secure ASP.NET Applications Guide
- Improving .NET Application Performance and Scalability Guide
- Improving Web Application Security Guide
- Performance Testing Guidance
- Team Development with Visual Studio Team Foundation Server Guide
- WCF Security Guide
Each body of work was several hundred pages of content, as well as a deep knowledge base, and in many cases, videos and multi-media, too.
Here ios a brief explanation of what happens along the way:
Design
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.
- Information Models – framing out the problem space and creating useful ways to organize, share, and act on the information.
- Content Types – testing which guidance types to use (how tos, checklists, guidelines, patterns, … etc.)
Execution
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.
Release
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.
Agile Publishing
We release our content modules along the way to test reactions, get feedback and reshape the approach as needed.
- Web site – we publish our guidance modules to a public Website 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.
- Desktop tool (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.
Stable Reference
Once we’ve tested and vetted the guidance and have made it through a few rounds of customer feedback, we push the guidance to an online Website as part of the library — in this case, the Microsoft Developer Network (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.
You Might Also Like
Agile Architecture Method
Agile Methodology in Microsoft patterns & practices
Extreme Programming at a Glance
How Agile and Lean Help Business
Roles on Agile Teams
Scrum at a Glance
Software Methodologies at a Glance
Waterfall to Agile
What is Agile?
