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 (26)
  1. Paul Evans says:

    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!

  2. 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.

  3. Piotr Czarnas says:

    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.

  4. ChilliCoder says:

    Well, yes, we do read documentation, at first, in the process, in the bus, with the boss 😛

    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)

  5. Ivaylo Bratoev says:

    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.

  6. Richard Back says:

    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!

  7. Don Smith, a Product Manager here at p&p, is asking for input on how we (p&p) should communicate…

  8. Don Smith, Product Manager at Patterns & Practices is asking for your feedback about how p&p…

  9. Don Smith, Product Manager at Patterns & Practices is asking for your feedback about how p&p…

  10. LockSmithDon says:

    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

  11. Phil Degenhardt says:

    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.

  12. The written guidance is absolutely essential to understanding how to use and extend the software factories.

  13. Apple says:

    Written guidance is absolutely neccesary but I think the video was much more effective.  With the video, you "see" how it is implemented and we get to hear your comments that written documentation just doesn’t convey.  In addition, our team could watch the video together and have discussions about it  afterwards.  This way, the team "gets" it and we can formulate our business solutions together.

    In addition, with the video, you get a sense of time.  What I mean by that is that going through a demo shows that within 60 minutes, you whipped up a solution quickly and it follows best practices and design.

    Isn’t that what you’re trying to accomplish with the software factory?  Good quality products and services quickly?

    As for the quality that the code produces, to be quite honest… The GAT and GAX was the most impressive because they’ve made the developer experience much better.  As for the deliverables of the web service factory itself, I think it provides a great foundation for consumers out of the box.  While it isn’t production ready, it’s definitely a great start.  Excellent job because it reduced my development time!!!

  14. The documentation is as good as any, a good starting point, and always welcome.

    Videos are always great. Screen-casts, etc.

    The bulletin boards on gotdotnet.com are almost unusable. I started trying to "give back" there but found the pain of keeping track and the fact that email is in reverse order way too overwhelming and cumbersome. A modern user form with RSS would be _very_ welcome. Nevermind a Wiki.

    I think you guys could get some bang-for-your-buck by letting the community help the community (agile: focus on enabling ‘tacit’ knowledge). I’d rather you guys spend time innovating and refining the codebase!

    Anyway – constructive criticism. All-in-all your steps are universally in the right direction!

  15. John Askew says:

    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. 😉

  16. AC says:

    I haven’t dug into your most recent releases yet, but on previous App Blocks from P&P the documentation was the thing that gave me my intial "wow, this is really good stuff" impression.  Explaining the requirements and why design decisions were made was especially valuable.

    Here’s a little story you may find amusing.  When evaluating one of the app blocks, some team members overruled and decided it would be easier to write their own than learn how to use someone else’s (they weren’t willing to spend a day with it).  Being the only one who really read the documentation, I was able to frame our not-invented-here development efforts in terms of the same requirements as the app block, and when they got hung up on some of the design decisions, I was able to recommend the same decisions (with reasons why) that were documented in the app block.  I can’t say the end result was _better_ than the app block, but it was definitely better than it would have been.  If you can’t join them, imitate them.

  17. Eduardo Marquez says:

    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.

  18. Jerry Nixon says:

    Remember, not all people learn the same way.

  19. Rich Mershon says:

    -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.

  20. Rich Mershon says:


    – 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.

  21. Declan says:

    I think a true ‘homepage for the WSF’ should exist with the essential ingredients for learning how to get to grips with them. I spent way too long looking around for written documentation on the subject. I think the current homepage is http://msdn2.microsoft.com/en-us/library/aa480534.aspx

    This page is not a good high level overview – rather it is a marketing blurb. What it really needs is a link to this article http://msdn.microsoft.com/msdnmag/issues/06/12/ServiceStation/ which overviews the architecture.

    Additionally, where it states on the homepage about the wealth of written documentation it is stated

    "Service Factory guidance is available in three basic forms:

    – Web Service Application Architecture

    Message Design in Service-Oriented Applications

    – Exception Handling in Service-Oriented Applications

    – Planning for and Migrating to WCF"

    … why not have a hyperlink to these articles. To this day, I still haven’t found them!

    Also, a direct link to a forum which can help the user with any problems encountered.

    Thanks for all the hard work!



  22. Frisky says:

    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…


  23. LockSmithDon says:

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

  24. David Cumps says:

    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 🙂

Comments are closed.

Skip to main content