Documentation by [insert doc type]
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).