I agree with the observations made in this article, with regards to structure and content. As a consumer of technical documentation, my top five pet-peeves are

I agree with the observations made in this article, with regards to structure and content. As a consumer of technical documentation, my top five pet-peeves are: 1. Long histories about the origins of the technology. I couldn't care less. For me, the purpose of reading a technical book is to accomplish something technical. Historical anecdotes, while interesting, don't help. 2. Overly complex code samples and projects. It is really easy for me to read a simple example and extrapolate that into something greater. It is more difficult to decipher a complex example, reduce it to its basic parts, and then extrapolate the few bits I need. This is why I don't like project books, where the author guides me through developing software to run a video store, for instance. The code samples are not self-contained and the likelihood I'm going to write video store software is literally zero. It is possible to explain complex ideas with short, self-contained code. I think Avdi Grimm does a good job of writing this kind of documentation. 3. Chapters that cover the installation of the technology on every operating system known to man. I'd rather Bing that information or have it in an appendix. There is no need to waste Chapter 2 delving into it. 4. API or library documentation that doesn't include code samples and clear descriptions of what I can pass in and what I should expect out. 5. Formatting. For example, I never liked Wrox books because of the minimalistic whitespace. The books probably contained excellent information, but the formatting was hard to look at and didn't leave any space for me to write annotations. During my career, I've found that the books that address these five issues are the books I tend to keep. They also seem to be the most popular in their respective communities.