The API Guessing Game

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 else.
• Good API documentation requires exactly two things:
  1. Working client code
  2. Explanation of how the you intend your API to be used
• Most API documentation has neither, and as a result, programming becomes an exercise in guessing the intent of the library authors. I call this the API Guessing Game.

• Writing “experimental” code for one specific function call, and running it repeatedly after little changes, to observe whether or not it succeeeds, what the return values are, etc…
• Having no idea how to start implementing an operation (even a common one) using the library…
• Having no which parts of the library are fundamental and unlikely to change, as opposed to those which are still under development…
• Being fairly sure that a specific class (or group of functions and data structures) is the right one for a specific purpose, but having no idea of the order in which the various functions are supposed to be called…

…because the authors didn't bother to write it down.

• 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.
• “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.)
• “Toy” examples (tiny demo apps which don't achieve anything of practical interest) are not nearly as helpful as examples that show the specific things that almost all of your users need to do.
• FAQs and Forums are useful only to the extent that they are searchable.
• If I have to search FAQs and Forums to figure out how to do something basic, which I know every other user will need to do, you're doing it wrong.
• Code examples (including code which is generated by any code-generation tools you provide) must represent your recommended coding style and order of operations.
• Always remember that, if I choose your library, I expect to continue to use it through multiple versions. You have to give me some clues about how to write client code which won't break too easily.

Choosing to use someone else's code library and API is (or should be) a buy-or-build decision—I choose to use your code because it's more cost-effective than writing my own. So,

• If I'm stuck using your code because there's no alternative (I'm looking at you, Microsoft and Apple), then your failure to provide and maintain adequate documentation is abuse of privilege and I will hate you for it.
• If your library is the best thing around, but your commercial license fees are exorbitant (I'm looking at you, Intel, and pretty much every DSP library vendor on the planet), your documentation had better be first-class or I will look elsewhere.
• If your library is free and/or open-source, I thank you from the bottom of my heart, and I realize your resources are limited, but consider your legacy. Either make an effort to provide documentation, or find a collaborator who can.
• Whoever you are, don't give me attitude. You may be very clever, but you're not that clever.