Documentation in EntLib 2.0: Some follow-up questions

I think my last post on this topic set a new record for number of responses to one of my posts within a day. (Yes, I know plenty of blogs generate more comments than this, but I'm still impressed!)

Overwhelmingly you seem to be asking for better examples in the documentation. To help us move forward on this, we have a few extra questions we are looking for input on:

1. Would you like us to focus most on adding examples in the API Reference docs (showing examples of particular classes and methods), or in the development and extensibility scenarios section (showing code samples to accomplish higher-level tasks)? I suspect most of you will choose option c (all of the above), and we can try to invest in both - but if we did bias one way or the other, which would you find most helpful?
2. Do you use the unit test code to help you understand how to use particular classes and methods? Would including unit test code in the docs as examples be useful? Or would it be more helpful to have code that looked more like real business code?
3. A few people have discussed the usefulness (or otherwise) of the Quickstart samples. Do you tend to look at the "Quickstart Walkthroughs" sections of the documentation in conjunction with the code, or do you just look at the solutions? Could we improve the walkthrough sections? Or could we do away with them altogether?

It's great to see so much enthusiasm out there for sharing your ideas. Please try to keep comments on this post related to the questions above. If you have any different suggestions or comments, please add them to the previous post.

Comments

• Anonymous
  July 12, 2005

1. adding examples in the API Reference docs (showing examples of particular classes and methods)
   
   
   I found the QuickStarts useful on the first day or two, but after that initial learning curve was over I want targeted information.

• Anonymous
  July 12, 2005
  I use the Walkthroughs where they are applicable. The inclusion of more business scenario code and Unit Test code would be nice as well.
  
  All in all, still an awesome help to some of us to have these modules, so, keep up the good work.
• Anonymous
  July 13, 2005
  1 - b
  2 - business code
  3 - documentation is preferred
• Anonymous
  July 14, 2005
  The comment has been removed
• Anonymous
  July 15, 2005
  the explanation in the Hands on Labs is great because it tells you what happens when you make a choice and why that choice is being made. To often I find it hard to decide what to choose or do not realize the potential consequences of a choice.
• Anonymous
  July 16, 2005

1. samples to accomplish higher-level tasks
   2. code that looked more like real business code
   3. NA

• Anonymous
  July 16, 2005
  Documentation regarding security and permissions needed to run Enterprise Library on Windows2003 within ASP.NET (Permissions needed in general would be useful). I have had a couple a significant issues with this:
  
  1) The error "Cannot open log for source {0}" when try to use the Exception Handlign and Logging blocks. This had to do with permissions to registry entries regarding the event log.
  
  2) WMI/Instrumentation security errors. I could not access WMI and when I was throwing exceptions from a Web Service I was seeing 15 seconds delay. This was due to thread being put to sleep for 5 seconds repeatedly due to WMI security /access errors.
  
  
• Anonymous
  July 20, 2005
  The comment has been removed
• Anonymous
  July 20, 2005
  The QuickStarts are great -- I think you met the goal of improving the "golden hour" experience. Actual samples in the docs should reflect real-world usage and/or particularly innovative usages of the blocks in conjunction with each other.
  
  I think the setup/usage/extension in real-world scenarios of the Config block is probably the most important and maybe one of the weaker areas.
  
  Finally - the introductory-level design docs for each block are good, but need to go about one level deeper as an aid to modifying the source. It is a little tough with this many projects/classes to figure out where exactly to go to modify / change behavior and guess what else might be affected.
• Anonymous
  July 21, 2005
  it's really difficult to set a prefered order since all are useful, perhabs should you consider a more continous delivery process for the training materials.
  
  timeframe 1:
  100% nunit (ready on drop
  50 % quickstart (augmented by troubleshooting as mark suggests)
  1 business scenario
  
  timeframe 2: (+0-2months)
  50 % quickstart
  more business scenario (perhabs as msdn article)
  
  timeframe 3: community support (+0-2quart)
  extension repository
  integration, test guideline
  
  if you integrate this commitment clearly (and it is by and large, for bigger product such as VS) i believe developers would be more attentive and satisfied
  
  a basic advise for writing to the web is to cut the length of your paragraph by 2 - for the offline doc and especially as the volume augments as it is the case with EntLib you should follow this process and prefer a continous training
  
  i've liked a lot the www.asp.net for that. the www.entlib.com / www.entlib.net are sadly both registred perhabs you could find and fill one still available (:
  
  PS: have you ever think about a quickstart <-> snippetManager integration
  
• Anonymous
  July 21, 2005
  ... of course msentlib.com is free
• Anonymous
  July 21, 2005
  I would like to see a bit more information regarding the exstensibility points. For example trying to write custom log sinks isn't helped when the example given is the most trivial example possible.
• Anonymous
  July 27, 2005
  The QuickStarts are great, and yes, I peruse the walkthroughs. Clearly everyone loves examples, and so do I. Particularly I would like to see one or two examples of extending the blocks.
  For example, the UIP block goes on for pages of just what you would need to do to implement 'isDirty' functionality - which was very informative, but I couldn't figure out why such an implementation wasn't included!
  So I guess what I really want are examples that are more in the format of:
  Here are a couple of things you likely would want to try, here's the final result, and now here is exactly how we did it and why.
  Which is just how Fred (my brain) likes to work . . .
• Anonymous
  July 28, 2005
  Yes, option c would be great, but the most I'm missing samples in the API reference. And it should be "real" samples ( not unit tests), that may be show how to use the specific functionality in a context. Also a bit more verbose remarks in the API reference which describes more of how this functionality is ment to be used, in what context, what to consider in using it, would be helpful.
  Concerning the quickstarts, I tend to look more at the solutions than using the walk throughs, once I got the basics of the building block. To get started and for first information, walk throughs are a probably considerd as a good means, but to be honest, most of the time, I start with them, but never get to the end of the walk through... I always end up, looking directly at the solutions.
• Anonymous
  July 29, 2005
  All options are great .. but please don't forget VB.NET users.
  
  Thanks
• Anonymous
  August 01, 2005

1. Hard choice but API reference docs comes first imho, but the absolutely most important part is well documented code using the documentation framework (for intellisense).
   
   2. Since most users should be interested in implementing EntLib (not refactor it) I think more business oriented code is a better approach.
   
   3. I always have the *.chm files open when looking at the code since this is the best approach for me to learn more about the framework.
   
   4. Okay, I know it wasn't four questions... but... More data on performance for different scenarios would be appreciated.