Tom Hollander's blog

patterns, practices and pontification

Documentation in EntLib 2.0: Some follow-up questions

Documentation in EntLib 2.0: Some follow-up questions

  • Comments 16

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.

  • 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.
  • 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.
  • 1 - b
    2 - business code
    3 - documentation is preferred
  • It's a good thing that you got these three questions into a post of their own, since I see them as entirely intertwined.

    The quickstarts (3) are important. There is no need to have them run through entire scenarios, but to a minimum get a basic scheme up and running. Business (2) like code is much more useful than unit tests. The latter could help coders understand the concept of unit tests, but that should be accomplished in a different context.

    Wrt 1, I definately must say option c. As for the quickstarts, the high-level examples doesn't neccessary need to be overly exhaustive, but they still need to be there in order to understand where the API level code fits. If you go indepth, it should be on API level.

    Thanks,
    Mikael Freidlitz
  • 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.
  • 1. samples to accomplish higher-level tasks
    2. code that looked more like real business code
    3. NA
  • 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.

  • 1. High level examples would be definitely be good. It seems like if you chop them up after you have them put together you could accomplish goal A as well. At a minimum, provide a link in the API docs over to the high level sample that appropriately demonstrates usage.
    2. The only time I looked at the unit tests was to take a peek at how you tested certain classes so I could structure my own tests a similar manner. The docs need more real-world type code. The one liner from the unit test is sometimes enough, but strip the Assert stuff off from it so the reader doesn't get the useful portion confused with the testing part.
    3. The quickstarts are definitely useful for figuring out some basic information but it seems like there are areas that they don't touch upon.

    I think one thing that is important is to have a way that someone can be guided to the right decision. For example, when I'm implementing exception hanlding, would I be better to catch 'Exception' and filter out the types based on the configuration in the policy? or would it be better to have a couple of different catch blocks for exceptions I know I might be likely to have to handle and have a seperate policy for each? These are the 'larger' questions that I think people are seeking some additional guidance on from something like a quick start or sample.
  • 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.
  • 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
  • ... of course msentlib.com is free
  • 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.
  • 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 . . .
  • 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.
  • All options are great .. but please don't forget VB.NET users.

    Thanks
Page 1 of 2 (16 items) 12