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”):
- Specific topics that are lacking in detail or are misleading
- New topics that you believe would be valuable
- Improving the balance of how much space we dedicate to topics like design, development, extensibility and operations
- Ways we can improve the structure of the content to make it more intuitive and easy to navigate
- Different formats or mechanisms to access the documentation that fit in with the way you work
- New ways to integrate the documentation with other resources such as blogs, community site etc.
- 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.