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?

Comments

• Anonymous
  September 03, 2006
  I have found the written documentation useful, and like to have something seperate from the source to print out and look through offline and away from the screen.
  
  I'll try and offer more constructive cristism when I've put more things from that and the samples in to practice.
  
  Thanks for all your hard work!

• Anonymous
  September 03, 2006
  I always start by reading the written guidance (or documentation) before using any of the product you made. I find them very usefull to get a conceptual overview of the product, framework or tool - including the samples provided in the documentation for each topic individually. Finally, when using the product, I also appreciate the possibility to get back and have a look at the reference section which can help me on specific topics. I would like to end up by saying that you are doing some great work, which is really usefull for the community and that can really save us time learning to use these (also great) products.

• Anonymous
  September 03, 2006
  Of course we read them. However they are not always complete. For example the documentation of Enterprise Library 2.0 is missing the description of the configuration building block.
  
  Other guidelines are missing a good description how applications should be designed to use a building block. Written guidelines also don't describe any sample applications and their step by step implementation using a given block.

• Anonymous
  September 04, 2006
  Well, yes, we do read documentation, at first, in the process, in the bus, with the boss :P
  Not always the documentation is clear, specially if you're not a native english speaker, but make a good starting point.
  I love HOL, makes documentation get real, not just definitions or abstract explanations.
  Good Work! (Y)

• Anonymous
  September 05, 2006
  Of cource I read them. When I researched the factories I always start with the documentation. From there I continue to the code then back to documentation and so on.
  The quality is good. Of course it could be better.
  I think that documentation should be kept as it is and we (the users) should start giving feedback not only on the code but on the documentation also.

• Anonymous
  September 05, 2006
  At first I skimmed the written guidance, so I knew where things were when I needed them. More recently I've dipped in to find things I need. I guess when I'm more au fait with things I'll read the rest for a comprehensive understanding.
  However the getting started notes for the factory don't mention the documentation other than instructions for getting the reference project going. The getting started guide points us at the HOL first, which is a cool thing in its own right, by the way.
  There should be more notes as to why the guidance packages generate code in a certain way, like the HOL does.
  But overall, the written documentation is essential!

• Anonymous
  September 06, 2006
  Don Smith, a Product Manager here at p&p, is asking for input on how we (p&p) should communicate...

• Anonymous
  September 06, 2006
  Don Smith, Product Manager at Patterns & Practices is asking for your feedback about how p&p...

• Anonymous
  September 06, 2006
  Don Smith, Product Manager at Patterns & Practices is asking for your feedback about how p&p...

• Anonymous
  September 07, 2006
  This is excellent feedback everyone. Thanks for taking the time to share and encourage others to share. Please keep it coming.
  
  I was just talking to Tom, and it turns out he blogged about EntLib documentation some time ago. We draw a distinction between written guidance and code/API documentation, but if you're interested in the feedback he got, check out his entry: http://blogs.msdn.com/tomholl/archive/2005/07/11/437692.aspx

• Anonymous
  September 07, 2006
  The Guidance documentation is some of the most useful stuff I've read in a long while. There is a plethora of technologies, tools, patterns, guidelines with which we're bombarded. It's often difficult to work your way through the various options. It is extremely valuable to have access to this sort of guidance. It helps me consider the relevant factors, make some decisions and get on with the job.

• Anonymous
  September 09, 2006
  The written guidance is absolutely essential to understanding how to use and extend the software factories.

• Anonymous
  September 12, 2006
  The comment has been removed

• Anonymous
  September 13, 2006
  The comment has been removed

• Anonymous
  September 14, 2006
  Yes, necessary. I read all first, given time. HOL are fabulous. I would like material designed to be used to present the software factories to my peers and perhaps at my .NET user group. Hire me. ;)

• Anonymous
  September 21, 2006
  The comment has been removed

• Anonymous
  September 26, 2006
  YES, written guidance is necessary!  It provides a frame of reference, and ditto all that has been written so far in pro of the WG.
  
  Some times it gets frustrating when the documentation lags behind, but we hang in there until the time comes that documentation is upadted.
  
  With the rapid change and the overwhelming amount of work, I think a Wiki would make sense.

• Anonymous
  October 20, 2006
  Remember, not all people learn the same way.

• Anonymous
  November 19, 2006
  -The written guidance is absolutely essential. I start there to get the "big picture" overview. -The quality of what I have seen in CAB and SCSF are generally excellent. Some minor editing problems like duplicated "Load Modules" text in ms-help://MS.VSCC.v80/MS.VSIPCC.v80/ms.scsf.2006jun/SCSF/html/02-040-Composite%20UI%20Application%20Block.htm -There is one thing lacking in the written guidance. While there are plenty of drawings to visually show part relationships, the drawings do not build a good mental image of how the smaller parts fit into the larger parts. After long reading and comparing you can build that image. I suggest you follow the excellent style used in your SQL Server 2005 online labs where it starts with a large visual map of the parts and then hi-lights each part as it goes into detail. This style gets my mind wrapped around the big picture quicker. Think of it as the "executive overview" to get a person visualizing the relationship of the parts quicker. I would like to feel more like I'm "zooming into" the drawing. There seems to be some inconsistent terminology in the various drawings that slows this mental map building.

• Anonymous
  November 19, 2006
  Also...

• In SCSF the docs on the Automated/Manual Recipes are excellent training aids. I had those printed out and next to me to walk me thru the steps the first few times until I had the process down pat. Comparing the Manual versions to the Automated versions was a huge help in understanding what was being added and where.
• Perhaps I missed something in CAB and SCSF but in order to easily picture the ABs, I eventually had to print out the classes that make up the hierarchy of inherited classes from ShellApplication down to CabApplication so that I could make my own drawing of the hierachy. I added method notes so that I could look at the drawing and readily figure out where I needed/could modify the flow of the process. I keep this drawing handy for reference. The information about how to modify the blocks is in the written guidance but is generally spread out among many sections. It would be nice to have a "big picture" drawing of the various entry points that can be added or modified.

• Anonymous
  February 08, 2007
  The comment has been removed

• Anonymous
  February 14, 2007
  I believe this could be updated greatly. First of all, I don't think you can do away with the written materials. So, note that as you read on. Secondly, the format for the written materials is a mess. It's just like trying to read the web. Yeah, all the information is probably there, but I don't have time to sift from link to link to link trying to figure a way to get through the information. I need a good old fashioned table of contents, and a contiguous set of chapters or articles that explain, in some logical progression, the concepts being presented. I need appendixes for background material I might not already understand. And, I need step by step instructions so I can get going immediatley. (And understand more as I go back and read later.) But, the number one thing that would improve all this, is to make videos of what you are trying to solve and how you approached it. Show us on the white-board while talking through it, then pull up Visual Studio and walk us through it. You have the supporting documentation for all the specifics and more advanced reading. So: TOC, Logical thought process, Videos, Videos, Videos... ;)

• Anonymous
  February 14, 2007
  FANTASTIC feedback everyone! Thank you so much, this will definitely influence what we do in the future. You guys rock.

• Anonymous
  May 04, 2007
  I am currently reading the written guidance and it's been really helpfull to give me an idea on the purpose of the software factory, together with 1 demonstration video which made me see the light ;) The written doc is also great when you have to document the choice for said architecture to management, the graphics and arguments described in the written docs are very convincing :)

• Anonymous
  November 27, 2007
  PingBack from http://feeds.maxblog.eu/item_264767.html