In a recent blog post, software developer/entrepreneur Ruben Vermeersch discussed the importance of documentation when supplying APIs to third parties. Although this seems obvious, he notes that few developers enjoy the tedium of writing documentation, and that many need a reminder to do so once in a while.
This importance is exemplified by the fact that few systems operate alone these days. Referencing Ticketmatic, he notes that the ticketing software is usually integrated with a website or some kind of planning software, and so the API is as important as the user interface. As a result, its documentation is as important.
The sentiment was extended by a post on Hacker News by user cbd1984 who stated that good documentation includes examples, but does not rely on them. The documentation tells users what an API can be used for, while good examples show how it should be used. Both are as important as the other to make an API useful.
To ensure APIs are consistently documented, Vermeersch encourages developers to introduce tooling that measures the coverage of the documentation. After every change, each API endpoint (method, parameter, result field, etc.) should be checked and cross-referenced with the documentation to make sure each one is covered by proper descriptions and comprehensive instructions.
However, extensive coverage alone is not enough: the documentation must be of a high quality. Vermeersch says, “No amount of metrics or tooling will guarantee the quality of the end result. Keeping quality up is a moral obligation shared by anyone in the team and that can never be replaced by software.”