Jaa

My Arm’s Broke, Fix Me - Three Levels of Guidance in patterns & practices

  • Artikkeli

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:

Comments

  • Anonymous
    February 08, 2011
    Way it is that most of links in something posted today already point to MSDN pages decorated with: "Retired Content This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. " ????

  • Anonymous
    February 08, 2011
    @ stic -- Because many of those links are to past projects that are archived.  The focus of the post is timeless -- the technical guidance is not.

  • Anonymous
    February 09, 2011
    @JD Meier - I was rather asking if we are going to see update anytime soon? .net 4 moved ahead, but it seems that MSDN doc was left a little behind :(

  • Anonymous
    February 09, 2011
    @ stic -- I don't think so.  I believe that for two reasons:

    1. I don't see it on the <a href="msdn.microsoft.com/.../bb232643">patterns & practices roadmap</a>.
    1. patterns & practices has a new model for guides that's different than the model I used.  For an example, see <a href="msdn.microsoft.com/.../ff423674.aspx">Claim& Guide</a>