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