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


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.

Comments (60)
  1. Chirs Brandt says:

    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.

  2. Shawn Cicoria says:

    I second the motion for examples. Succinct and multiple as well.

    Nothing feeds the mind better than a concrete usage point.

  3. AZDeveloper says:

    Same here. QuickStart’s are good but are no substitute for examples in the help itself.

  4. Andrew Cave says:

    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.

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

  6. Vern Reeve says:

    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.

  7. Daren Hawes says:

    How about a PDF version. I like printing manuals for office use, but the online help prints badly.

  8. Serge Matsevilo says:

    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

  9. Chuck Sullivan says:

    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

  10. I want the example of more various cases.

    like Hands on lab.

  11. Matthew says:

    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.

  12. Matthew says:

    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.

  13. I would like to see ASP.NET examples if possible. Would also like to see more samples that incorporate multiple blocks.

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

  15. Todd Davis says:

    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?

  16. V.Pena says:

    As suggested earlier by Daren Hawes, it would be tremendously helpful to have a PDF version of the entire EntLib docs.

    It would be great to have a single documentation file that would print in an organized, well formatted version with page numbers, headers and perhaps even an index.

    Thanks!

  17. cs says:

    I would really like the unit tests documented better.

    Take what is found at:

    http://www.agileprogrammer.com/oneagilecoder/archive/2005/04/07/3162.aspx

    Update it if it needs updating and put it in the readme. It wouldn’t to have a little more detail as well. Also note if there is anything for VS2005 beta 2 that should be done differently.

    I’ve also run into problems where some unit tests keep looking for the 1.0.0.0 version of EntLib assemblies instead of the 1.1.0.0 version.

  18. Praveen says:

    Performance benchmarks: It will be nice to see in one section of the documentation contain how a decision can be reached in using enterprise library inside thin, small, medium and large projects. What I meant is specific memory and usage benchmarks against multiple hosts (ASP.NET or Custom hosts) and if possible a measurement of development effort. This will help decision makers to choose EL, the least for small projects.

  19. Chuck Boyer says:

    I’d really like to see better docs on deployment scenarios. I’ve been struggling with an asp.net deployment for several months and just today got it working. After scouring the team’s blogs, other sites and getting friendly with google I finally got it working. Now, my problem is being able to repeat it…I tried so many different things, I couldn’t tell you what really worked.

    You guys are doing a great job making my job easier! Thanks for the hard work!

  20. Ben Scott says:

    More examples, particularly in the area of custom providers, deployment and ASP.NET. I have managed to piece together this information from P&P blogs, webcasts and other google bits & pieces. It would be great to have it all in one location. The PDF idea is also great (I do a lot of reading on my PDA)

  21. Jon Paal says:

    need to know system requirements and whether or not this is usefulfor asp.net web development.

    (Without visual studio!)

  22. Naresh Koka says:

    I am with others with respect to request for examples in the documentation.

    How about step by step instructions to create a minimal custom provider?

    I’d like to see a paper/description on an approach for decision making process of when to use an EL block and when not to.

  23. Pawan Nayak says:

    Scenario based examples, illustrations, focus on applicability of the technology advancement. Comparison between the old and new technology. Lots of tips and warnings.

  24. Julio Casal says:

    Well, I vote for more enterprise examples. I mean, it is usefull for me to learn from the examples and hands on labs of each of the App Blocks, but I would really apreciate to see a complete example which makes use of all the capabilities of the Ent Lib in a blue print application with a great architecture. That would be great!

  25. Tom asks the question “Where do you want your documentation to go today?” here.  Please…

  26. Tony Wall says:

    Help 2 format is fine. PDF can be produced by "print to PDF" virtual printer driver or with full Adobe version (maybe you could do that aswell if you have it, to keep everyone happy). PDF iss nice but I don’t find that useful as the primary format. MSDN style (help 2) is the best in my opinion.

    But please provide a merge module for the Documentation, so that we don’t have to edit the MSI help tables to redistribute it. That took me about a day to complete.

    Maybe you could include the Help 2 source projects aswell, but I still don’t see any value in that (since Help 2 can reverse engineer anyway) as there seems to be no installer for Help 2 that automatically populates the Help tables in the target MSI (did I miss it?). Maybe you could write one or have one at MS already you can let us all have, now that would be useful!

  27. Andrew Mackie says:

    Deployment, deployment, deployment!!! Needs documenting much better, for the various scenarios.

    Compiling with/without instrumentation, and what problems will occur if running as least-privilege users.

    Using the WMI sink with the Logging block – needs documenting.

    (just where do those messages go to…ah, OK, need some sort of WMI event viewer, but how do we differentiate different apps all sending the same WMI event ? … )

    Hands on labs – cool! Should be included as part of the default install. Web-casts, on-line docs etc. are all great, but it’s easy to get lost in the morass of information. The step-by-step hands on labs have been essential, IMO.

    Include all the web-casts & slides in the default installation ? Or at least put a short-cut link on the start-menu to the pnplive web-site. There’s tons of useful info there, that some people might not be aware of.

    How to maintain application specific config settings via the config tool, without having to write lots of designer code. The approach at http://blog.hishambaz.com/archive/2005/01/30/197.aspx requires lots of coding, but the approach at http://bloggingabout.net/blogs/olaf/archive/2005/04/18/3488.aspx sounds potentially more promising.

    What "essential" add-ons are needed ? e.g.

    Rolling file sink.

    DAAB for Oracle ? Is it there yet – how many "essential" patches/work-arounds need applying for real-world use ?.

  28. Bill Lush says:

    I agree with most people about more examples.

    I did like the quickstarts and found them very useful. I think there should be other quickstart applications that show how an application will fit together when it is making use of more than one application block.

    I also found very little documentation on how to build an application in a remoted environment and how the Exception Handling Application Block could pass exceptions back down the remote channel so the client could get an understandable exception message. Still with remoting it was not clear if Application Blocks functionality is serailizable, by that I mean whether I could pass the objects as parameters to a remote system.

  29. Jonathan says:

    The things I would like to see are the things that I basically had to find out by myself:

    – Example/sample code showing how to create providers through their factories using a custom configuration file (i.e. not the web or app.config file)

    – Example/sample code showing how to create your own provider (I created a custom DbAuthenticationProvider to match my project’s requirements). In the current documentation there is very little on how to create your own, custom providers. I had to find out basically by copy/pasting the existing code and modifying it till it suited.

    – Best practices in managing the Enterprise library in development teams through to deployment to production.

  30. I think more tips and tricks will add alot to your documentaion. usually I people uses Blogs to find such details in how you can fine tune enterprise library to your need. any way great efforts guys. Appreciated

  31. Dean says:

    Integration with the VS.Net help so that when I want Help about the EL methods it is readily available. O’reilly has a pretty nice approach for adding additional Help files to VS.Net to complement their Nutshell book series, it even works with Dynamic Help.

    Discussions of the pros/cons of various options. It is nice that there are so many ways to do something, but I need some help figuring out when to choose one approach over another, and even whether I need to bother at all. I build small scale web apps and I can seldom tell when a specific technique will really be necessary/helpful.

  32. Absolutely, please, please include a merge module for the documentation! I spent two days trying to get one together with little success (until I learned about the help integration wizard: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vstechart/html/integration_wizard.asp).

    Why? There are a few changes we maintain in EL, the least of which is signing the code and the better way of deploying this was to "repackage" the EL code with our changes in our own installer (with our own framework and tools too). Otherwise, all of our developers would have to install a new EL, then copy over our changes, etc.

    On the topic of actual help content, I agree that the examples are a bit light and some areas are shallow in their description. However, that is usually the case when you are working something specific or "non-standard". Remember, these are building blocks not final assembly pieces. My recommendation would be to keep help similar to the way it is, but have an online version that allows comments on each comments page (see this example from PHP.NET: http://www.php.net/manual/en/language.functions.php). This way when the community does something specific there is a place to record it, then the EL team can consider placing those changes in the next release.

  33. Greg says:

    A complete Visio UML class diagram of the entire Enterprise Library, a separate page for security, data access, caching, etc. My version of Visio (10.0.5110) will not reverse engineer the EL projects properly.

  34. Robert says:

    I’d like to see increased deployment scenarios documented. Particularly from the situation I am in (and I susupect many others too), namely I develop with VS.Net on my development machine with Admin rights, but I deploy onto prod machines (in my case, owned and managed by my clients) where the app runs under minimal rights, and where I have no hope of altering the rights/permisssions.

    Also;

    Step-by-step rebuilding of the library without

    instrumentation.

    Step-by-step strong naming.

    Step-by-step installation to the GAC (for dev machines)

    Step-by-step installation to the GAC (on production machines as part of an application install).

    As everyone else says, more examples, but I’d like more examples/tutorials for custom block development, from simple config settings, to configs with collections etc.

    While I’m here, I’d like to say I thought the docs for EntLib v1 to be excellent. Keep it up, and if you can, beat your own high standard….

  35. Jackson says:

    UML or DSL diagrams would be ideal for design phase inclusion. They would also help us train more junior developers both in proper use of the library and proper use of DSLs and UML.

    Also: terse, inline examples in the documentation for specific implementations. Something we could cut and paste would be great!

  36. Roumen says:

    I would like to see more sophisticated examples using the library. The provided examples are too simple and don’t really cover enterprise scenarios. How about an example of populating a dataset with master detail relational tables and then updating the database handling concurrency and dependency issues? I think that would cover the needs of many EL users.

    Thank you.

  37. Jonathan Matt says:

    Organized, searchable examples!

    To be specific: I decided to try the SQL Strage Provider for a Config Block section. After hours of searching I finally found an old forum post with some information on how to use it (didn’t even know there was a SQL script for the stored procedures!)

    Don’t mean to sound ungrateful, our code has helped me a great deal

  38. Tom Gilkison says:

    When I was at the Ent Lib Edunar in Sacramento with Ron Jacobs, I asked him to poll the group on the types of applications they were developing. ASP.NET outnumbered Windows by far. When I filled out the survey, I requested more ASP.NET examples in the documentation. ASP.NET / C# is the majority of application development right now.

    Not only do we need more examples, but we need Webcasts that are educationally deep instead of overviews of the product. Show me how to create an application using the tools you are providing. Show me application sharing of Visual Studio. Cut down on the PowerPoints.

    Show me how to solve problems in different ways. Show me code, code, and more code. Tell me how it all works together, but show me code examples.

    Try it out before you sell it. Walk me through a deployment example in an Enterprise environment. Make sure the product works before I find out that it doesn’t.

  39. Tom Brown says:

    Examples, more VB.NET Examples and a Glossary of Terms.

    Examples: Nearly everyone has said it so far. I would prefer really simple examples for virtually every public property/method that doesn’t use basic data types. I like to find out new stuff by trial and error. e.g I do a quick search and the "DoSomthing(foobar)" method sounds like its what I need so I’ll try it out, but whats a "foobar", how do I get one, do I need to populate it first, or will a blank one do. You guys who wrote the thing know what a foobar is, its obvious to you as you’ve been working with it for months, its so obvious you don’t think you need to even mention it, but not me – (just a lazy user) – I’m looking for something quickly, I don’t really want to read all the help for the class, I just want to try out the DoSomething method and see if it works for me, and I’m stuck because I’m not using the foobar object correctly.

    Glossary: list of simple succinct definitions, and expansion of acronyms

    However having said that, Enterprise library has been really good so far and I’ve always managed to do what I wanted with it, either using the help or search engines. I particularly like the existing quickstart walkthroughs in the help, even though they’re in C#, I can work out the VB equivalent.

  40. Tom Brown:

    Could you let me know which walkthroughs are in C# only? All of the samples should be in both VB and C# – so if we missed any, we want to get this fixed. Note that there is a "Filter" option in the help that lets you show/hide the samples in individual languages.

    Tom

  41. Emil Damian says:

    Give us a full enterprise scale application blueprint. Stop hidding behind your fingers!

  42. I think my last post on this topic set a new record for number of responses to one of my posts within…

  43. Francois Tanguay says:

    Sequence and class diagrams for mainly used scenarios.

    Show in a glimpse how ConfigurationManager, storage providers, transformers config watcher factory, config watcher, cache interact.

    I miss those a lot and is the first thing I’d create when looking at source code and wanted to share with peers.

  44. aaron meis says:

    The biggest thing I would like to see is more hands on labs, specifically focusing on the creating your own app block. Having the hands on labs was the real selling point to our team and one of the main factors it was so easy to adopt. With semi-real world applicable examples we were off and running. Maybe also an example of an existing web app that is "magically" transformed into using the app blocks. That would be a great help.

  45. Dave Owens says:

    As with all the other .NET documentation (books, help, articles, etc.), I ache for the Enterprise Library Documentation to make far more ambitious use of "a picture is worth a thousand words".

    OK. Ambitiously, I’d like a diagram that positions/lays out:

    1) the Enterprise Library classes, each with a terse description of its role

    2) position all the client software

    3) position all possible enhancements — hierarchies, validation, etc.

    Use all applicable graphical techniques — fonts, color, etc. Don’t worry about page size. Just make the diagram big enough to "include everything useful".

    With such a diagram, I believe many overviews and other excuses for run-on prose would disappear. That is, tightly couple the discussion prose with the diagram. In the accompanying prose, take passes through the diagram. Discuss it horizontally for Enterprise-Library functionality breadth. Discuss the diagram vertically for in-depth power/robustness/enhanceability.

    Clear? Please ask questions…

  46. Maxim Michtchenko says:

    I will repeat a number of people before me – Code examples should be added to documentations.

    Hands On labs are very helpful but they are very basic too, expansion in this direction will be very much appreciated.

    All the philosophy of the enterprise libraries are based on configuration block – everything is created form configuration file, however I came across one case where I was not able to use config block to initialise database – it took me a while to find out the solution. It would be nice to have code example for non config originated objects in the documentation.

    Last thing – it would be nice if non-instrumental configuration will be included into the solution.

  47. Dave Owens says:

    Yes, I saw your new post and it deserves good answers. However, today, as a follow-up and continuing with your first post, I’m brimming with a truly out-of-the-box idea!

    To help sell my "one powerful EL-documentation diagram", understand that it could offer two important solutions — voluntary documentation and centralization. Since publishing "a diagram, plus sufficient accompanying examples and prose" is probably too much work in one shot, why not consider this? For the first documentation release, why not offer a diagram PLUS guidelines for voluntary other-user documentation. That is, centralize the diagram at the MSDN site and make it a combined centralized documentation, plus voluntary articles, plus forum questions site?

    For my interests, right now, the best EL documentation is sprinkled all over. Some of it is in the Help, some in the Hands On Labs, and the rest in Doug Rohrer’s and HizHambaz’s articles. Thus an important fraction of my time is spent cutting and pasting into Microsoft Word, Googling and printing. To make it easier, if you let users forum, and write articles at a central site, it would help a lot. Naively, all I believe you need are robust guidelines and a central site.

    A qualifier about my original diagram idea. Note, that I believe my diagram idea is NOT the same as UML. Rather, I want a diagram that strongly accompanies good multi-pass prose (horizontal and vertical across diagram). To me, by contrast, UML itself would be clunky — not go well with prose. Please comment. I may be out of my league.

    Perhaps another savings. Ideally, a good diagram should ultimately replace the Table of Contents and maybe the Index.

    Another fun idea to explore is to play with Icons. Why not use Icons as a documentation tool? That is, assign icons to the most used classes and then refer to such classes in the diagram and the accompanying prose by their icons?

    Yes, I understand I’m delegating a huge amount of work. Still, doesn’t the power of the Enterprise Library deserve the most powerful documentation? Nothing ventured, nothing gained…

    I’d love to see some replies…

    Dave

  48. Mark Wallis says:

    I’d like to see Google like search capability and more importantly…search results. i.e. The best match at the top of a list and a breif snapshot of the contents of the page.

    I also agree with the need for better examples. Most of us are used to ‘Googling’ for technical how to’s and I personally I’ll go to Google before going to MSDN. The reason is, I find that posted articles always have more real world (and therefore useful) examples.

    Mark

  49. Alex says:

    i’ve build application blocks (dlls) for other companies before but my current company wants to use something ready-made and from Microsoft so off i went and found EL. to my suprise i find little documentation as to how to use these blocks in real multi-tiered code. we build our apps with presentation/business/entity/data access tiers like all good boys and girls and i’d like to see how to use the ExceptionHandling/Logging/Caching/Configuration/DataAccess/etc blocks in just such an environment. the samples i find are ridiculously primitive if not misleading. i’m sure there are examples of just that but i’m looking in the wrong places. or am i?…. thank you for your efforts.

  50. Thanks Alex. The QuickStarts are deliberately very simple, as we didn’t want to clutter the example block code with a whole bunch of code which is important in a real app but unrelated to the actual block usage. We do understand that seeing all of the blocks in a realistic application is also important. We already have one sample that uses EntLib in the form of the WS-I Basic Security Profile Sample Application. We plan to have some more rich sample deliverables available in the months after EntLib for .NET 2.0 is released.

    Tom

  51. Praxa says:

    Best Practices in multi tiered Apps using ExceptionPolicy.HandleException with Transactions: try, catch, finally(close connection), Rollback encapsulated within try,catch.

    So far so good – thanks.

  52. jani says:

    I’d really like to see:

    – integrated user interface application block, optionaly with some sort of master application activity (task) management

    – distributed transactions support in Data access application block

    – strong naming and stronger distribution support

  53. Steven Perry says:

    Echo "More Examples", plus….

    1) Examples using it with other Microsoft Blocks that are available.

    2) Integrated VS Support.

    3) Deployment. This includes compile options for the library, how to utilize the blocks in a multi-tier environment (Remoting), can components of the block be seperated onto defferent physical platforms (Place the DAAB on the database server, etc.)

    4) Smaller, more consise examples that solve specific problems. (ex. In VS, you can create a DataProvider and use VS to manage that DP. How can one use the EntLib with the VS environment?

    Just a few of my thoughts.

    Thanks.

  54. Robert Gaston says:

    I’m partial to end-to-end examples, since "best practices" are often conflicting; for example, performance, security, and maintanability requirements tend to oppose each other.

    I think an SOA example, maybe with win/web/mobile clients, that uses all the blocks would be great, and maybe could serve as a template. Perhaps the WS-I example covers a lot of this, honestly I haven’t reviewed it yet.

  55. Nanda says:

    More examples is always good.

    How about some help regarding how to extend the application blocks.

  56. Alex says:

    Specific examples such as:

    – Typical Update, Insert, Delete, Select queries used to fill datasets for the major DB platforms (Sql, Oracle, etc)

    – At least one example of the Data Access Block banging on Oracle

  57. Michael Schaefer says:

    I’m actually unable to read ANY of the documentation. All the files in the Docs folder end in an .HxC, .HxK or .HxT extension. I’m sure it’s just a simple issue of having the right reader installed. But this is costing me ramp up time. Would have been nice if the documentation was deployed in some standard format such as PDF or HTML files so that I could read them without this hassle.

  58. Jon Paal says:

    Please fix the font size in the help files. The font is waaaay too small and the size is locked down !

    The size of the font needs to be adjustable for those who need to read larger text.

  59. Scott Munro says:

    A lot of developers feel much more comfortable exploring a new technology by checking out some example…

Comments are closed.

Skip to main content