Some day I intend to write an eloquent essay on the virtues of good software documentation, particularly as it applies to software libraries for use by other programmers. For the moment, I will say only this:

• Once one achieves a basic level of coding competence, programming mainly involves choosing appropriate libraries, understanding their APIs, and debugging.
• All three aspects require good documentation above all.
• The greatest library/API design in the world is no use if programmers can't figure out how to use it.
• A few cryptic comments, processed through Doxygen, are not sufficient.
• Good API documentation requires exactly two things:
  1. Working client code
  2. Explanation of how the API is supposed to be used
• Most API documentation has neither.
• “Kitchen-sink” demo code (one giant demo app) is not nearly as useful as multiple smaller demos.
• (But one kitchen-sink demo is better than nothing.)