The Evil Blog

One of my favorite type math jokes are the often sited proof by … (search for “proof by”) jokes. The reason why I find them especially funny is that they often strike earily close to real world examples.

I’ve recently pondered that a similar structure governs software API documentation. So without further ado I bring you the Documentation by … list:

• Mailing list discussion – You point users to a highly technical, multi-threaded, mailing list discussion that was held on a public mailing list several years ago
• IRC log – The project does not contain any documentation. If you track down the maintainer he/she will point you to an age old IRC log
• Intimidation – The README states “The API is pretty obvious so no documentation should be needed”
• Lazy programming – If you punk a developer via mail or IRC there is a slim (and slightly increased) chance that he/she might add a section about you questions to the docs
• Binary blob – If you just stick in a binary blob you don’t have to document it. Everybody knows that
• Incomplete wiki – No documentation as such, but users and contributors are encouraged to put their experiences on the projects wiki
• Empty autogenerated docs – When you compile the doc target you get nice html pages naming all methods of the library, but no written documentation abou the methods. This is the javadoc classic
• Self documenting code – It should be pretty obvious how this documentation style works
• Example – Put in one example that covers approximately 5% of the API
• Broken link – Somewhere in a readme you put a link to a long dead webserver which supposedly contained some documentation. Maybe the wayback engine has it?
• Multi volume novel – Write several hundred pages of textual documentation with figures and graphs. However do not include a browsable API overview or any structured presentation of the API
• Bloogle - In between the sporadic rants on the developers blog you will find the documentation. The API consumers must use Google to find it.
• Your favorite – Not seeing your favorite documentation style here? Please add it in the comments

Update: I missed one glaringly obvious doc type. The documentation by “Bloogle” (second last on the list).

Tags: documentation, humor, math

This entry was posted on Saturday, April 19th, 2008 at 03:02 and is filed under Hacking. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.