Early in my patterns & practices days, each time I built a new team, we had a hard time figuring out what level to cater our writing for because we had such a variety of audience, even among architects.

After a lot of pain, we finally adopted a three-level system that serves us very well.  It helped us focus our writing and nail problems in an incremental way.  You’ll never see this in our docs, but it shaped how we prioritize our docs.  We used three levels …

Three Levels of Guidance
Here is the behind-the-scenes look at how we talked about these three levels of guidance on the team:

1. Level 1 - “My Arm’s Broke, Fix Me” – This is where a customer is in pain, and just wants the fix.  You’re in the emergency room, and you just want the doctor to do their job and just fix it.  Sure, there might be lots of ways to fix it, but for now, just give me one that works.  Make it step by step.  Don’t’ make me think.  Level 1 – “My Arm’s Broke, Fix Me” guidance is great for scenarios where you are either under the gun, don’t have the time, or just don’t care about the intimate details and just want to make it work.  (If you’ve ever been presented with a bunch of options and can’t figure out a single path, you can especially appreciate this.  This was our answer to, just give me a proven practice and be done with it.)  We turned this level of prescriptive guidance into How Tos.  Here are examples of Security How Tos.  We also turned these into whiteboard solutions, or "Application Scenarios.”  Here are some examples of Application Scenarios.
2. Level 2 –“Show Me All the Options” – This is where you want the options on the table.  Don’t just give me a recommendation, give me the options, and I’ll pick my path.  Or if you are going to give me a recommendation, lead up to it.  Give me all the options, then suggest what might work for me.  Level 2 – “Show Me All the Options” is good for scenarios where, the reader is smarter than the canned solution, or is a skeptic, has the time to think through the options, or wants to be involved in the solution.  It’s about exposing the thinking.   Here is an example of Level 2 – “Show Me All the Options” where we exposed Authentication and Authorization patterns in ASP.NET.  Eventually we found a way to combine the benefits of Level 1 – “My Arm’s Broke, Fix Me” with Level 2 – “Show Me All the Options” by creating a matrix of options + adding scenario-based recommendations.  Here is an example of a matrix of options with scenario-based recommendations, with our Cheat Sheet – Data Access Technology Options.
3. Level 3 - “I Live for this Stuff” – This is where I’ve got all the time in the world and I love reading about this stuff on the weekends.  Throw all the “blah, blah, blah” my way and the intimate details and I will happily engulf it to no end.  You can’t overload me with too much minutia and I want all the stories or elaboration you can muster.  Your knowledge of the nooks and crannies is my amusement.  Explained – Forms Authentication in ASP.NET and Explained – Windows Authentication in ASP.NET are good examples of this level of guidance.  Security Fundamentals for Web Services,  Threats and Countermeasures for Web Services, and Authentication, Authorization, and Identities in WCF is another good example of this level of guidance.

Prioritizing Guidance
As a rule of thumb, we decided that we would focus on first addressing Level 1 – “My Arm’s Broke, Fix Me.”  This way, we could at least leave a trail of proven practices and pave a path of success.  As a result, many of the guides I shipped from patterns & practices are heavy on “How Tos.”  In fact, the guides are really “action guides.”  The first half of the guide, sets the stage by sharing mental models, key concepts, and principles.  This is optimized for reading in a sequential flow, but still modular so you can hop around.  The second half of the guides is a focus on “action” and is a set of action modules (Cheat Sheets, Checklists, Guidelines, How Tos).  It’s optimized for random access, and the individual modules link back to the related items.

This simple way to think about the majority of our guidance helped us significantly priorities the work we did for the following projects:

• Application Architecture Guide
• Building Secure ASP.NET Applications
• Improving .NET Application Performance and Scalability
• Improving Web Application Security – Threats and Countermeasures
• Improving Web Services Security
• Performance Testing Guidance for Web Applications
• Security Engineering for Applications
• Team Development with Visual Studio Team Foundation Server