Written Guidance. Necessary?

In my last post I mentioned that we are having a lot of hallway discussions lately. Another topic that is getting a lot of airtime lately is written guidance. As you know, the patterns & practices team has been producing written guidance since the team was created. Over the years we've evolved the the code-based guidance considerably - from reference implementations and application blocks to software factories that contain guidance package (code generation), the written guidance has pretty much stayed the same. This may or may not be a problem, but there inlies the problem - we don't know. We actually get VERY LITTLE feedback on written guidance. That could mean one of a few things: it is perfect and can't be improved, no one is reading it, or no one cares. If it has no need for improvement, great, but I find that hard to believe. If no one is reading it or doesn't care, THAT is a problem. We invest a lot resources into the parts of the deliverables you can read and print. If those resources can be repurposed - that would be a good thing to know. I would love for you all to educate me with some comments. Feel free to use the questions as examples of the things we're interested in. Thanks!

  • If you've downloaded any of the factories, did you read any of the written guidance?
  • If so, when did you read it? before doing anything else? only when you ran into a problem? when you were interested in the rationale behind the guidance?
  • Did you find what you were looking for? What is your impression of the overall quality?
  • What are the most important sections (how-tos, patterns, explained, etc)?
  • Should we continue to make investments in written guidance? should we increase or cut back?