Tom Hollander's blog

patterns, practices and pontification

Documentation in Enterprise Library for .NET 2.0 - What would you like to see?

Documentation in Enterprise Library for .NET 2.0 - What would you like to see?

  • Comments 60

Working on technical documentation can seem like a bit of a thankless task at times. When it is done poorly, everybody will complain loudly about it. On the other hand, if it is done well, most people don't think about it at all. So overall I am taking it as a compliment to the Enterprise Library team that nobody seems to have a lot to say about the quality of the docs, since we used to get a lot more negative feedback about the documentation in some of the original application blocks.

Nevertheless, we are not satisfied with having documentation that everyone is indifferent to - we want you to get excited about it! (On a few occasions when I've been in the interview loop for tech writer positions, I always ask the candidate what is the best piece of technical writing they have ever seen. It's a tricky question that often leads to entertaining answers, such as a description of why a particular vacuum cleaner manual was so damn good :-). While we have a few ideas on ways we can improve the docs in Enterprise Library for .NET 2.0, we'd like to hear your ideas to move the docs from "ho hum" to "wow!".

Some examples of the types of feedback we are looking for are (in increasing order of "thinking outside the box"):

  1. Specific topics that are lacking in detail or are misleading
  2. New topics that you believe would be valuable
  3. Improving the balance of how much space we dedicate to topics like design, development, extensibility and operations
  4. Ways we can improve the structure of the content to make it more intuitive and easy to navigate
  5. Different formats or mechanisms to access the documentation that fit in with the way you work
  6. New ways to integrate the documentation with other resources such as blogs, community site etc.
  7. Something so way-out-there that it can't be classified :-)

Make sure you think about these questions in the context of all of the Enterprise Library documentation, including the block overview content, the API reference docs, and the Enterprise Library-wide content such as "Building your own block".

We already have a list of things we are considering which I'll happily share - but first I'd like to hear your thoughts so we can make sure we are heading down the right track.

Update (July 12th): Wow - thanks for everyone who has posted comments so far. It seems that more than a few of you would like to see some better examples! We'll take this into consideration for v2. In the meantime, to make the forum more interesting for everybody, you may want to think about some other areas for improvement. Even if you don't ask for better examples, we've definitely heard the message that you want them!

Update #2 (July 12th): I've added a new post with some related follow-up questions - we're looking forward to hearing your ideas.

  • In general, I think the Code Documentation needs more examples. I appreciate having the QuickStarts, but I don't like having to open a QuickStart solution just to see how to use an element.

    I think the Key Scenarios are great and the design diagrams are great helpers to putting each block into context.
  • I second the motion for examples. Succinct and multiple as well.

    Nothing feeds the mind better than a concrete usage point.

  • Same here. QuickStart's are good but are no substitute for examples in the help itself.
  • Have to echo what Chris says with the examples and add include some more documentation on deployment. The WMI instrumentation caught us out, found the information we needed in a Blog.
  • I have to say that more examples, especially ones that focus on the more complex cases, such as correctly using connections, and handling errors thrown by the various blocks.

    The quickstarts are nice but take too long to open, how about live links to web examples as well?

    Deployment and strong naming are big deals to us, please focus on exactly how to deploy and when to strong name etc.
  • More Examples using a wider variety of data types. For example, just recently, I was trying to get a decimal field from a stored procedure using the dbCommandWrapper.AddOutParameter. But it wasn't returning the decimal places. I found out that AddOutParameter doesn't support specifying the precision and had to use AddParameter instead. So the data access examples should include a string, integer, decimal, and datetime data types.
  • How about a PDF version. I like printing manuals for office use, but the online help prints badly.
  • I agree on code examples in the documentation. That is the fist thing people are looking for when they integrate it into their solutions.
    More examples for all common and some less common scenarious would help a lot.
    We also do read code when we need answers to very specific questions. Perhaps this would help: http://www.codeproject.com/gen/design/APIUsabilityArticle.asp
  • You're right, in many ways.

    Great documentation goes with having a great product. It is hard to do, maybe even harder than the coding in some ways.

    I concur with the need for more examples. I prefer them simple and cumulative not monolithic. Many of the demo projects for previous technologies have been just to darn hard to set up.

    The key is to have a good basline example of using Config, Data, Exception/Logging, and to work other examples in using this as a base.

    A soup to nuts example like F&M may be more than I got bandwidth for, and too redolant of someone else's design. Snippits I can purloin and apply quickly are much more appealing.

    Regarding feeback, technotes, examples and such -- mainstream it on MSDN and supplement on GotDotNet ... but put the effort (and resources) into making these living breathing communities hosted by people that live and breath this stuff.

    Navillus
  • I want the example of more various cases.
    like Hands on lab.
  • I agree with everyone else so far - it looks like there are a lot of common pain points in the documentation.

    The big lack for me is the breadth and depth of examples for using the Oracle data provider. I'm developing an application that needs to run on both SQL Server 2000 and Oracle 10g, and although the DAAB gets me a lot of great functionality, I have to fight to add each new feature, and I don't know if I'm using the features that are there correctly or to their best effect.
  • The help file does not include the Common Assembly. There are very important classes and functionality the should be used here that we must search the source code for.

    It looks like the code has comments but it is not being included in the help file.

    The project or ndoc file for the help file should be part of the project.
  • I would like to see ASP.NET examples if possible. Would also like to see more samples that incorporate multiple blocks.
  • I'd love to see examples of where the patterns differ from the 1.1 release. I keep reading the 1.1 EntLib release will work with 2.0, but do not provide the recommended guidance and patterns to take full advantage of the 2.0 framework. Some type of documentation driving home the differences would be a huge help.

    Perhaps a stand alone document outlining the differences, and within the documentation noting differences when they are there? Would anyone else find this type of documentation useful?

    Just a thought...
  • I had to laugh - before I read any of the comments, the first thought that came to mind was "more examples", and then I see that same thought echoed here again and again.

    The technical docs are great, but what we really want are practical examples. I have to admit that the Hands On Labs are EXCELLENT, much more helpful that the QuickStarts, by leaps and bounds.

    The MSDN docs often have the technical info, followed by an example. That works great as well, maybe something you can implement?
Page 1 of 4 (60 items) 1234