Why Writing Quality API Documentation Matters

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.”

Original Article

An API is only as good as its documentation

Martin W Brennan Martin W Brennan is a co-founder of ViewPop, the social network that puts the creation of 3D photos and videos in the hands of anyone with a smartphone. For his day job, Martin is a copywriting consultant at We Write Words, learning about the world as he writes about it.




I couldn't agree more!

At www.miredot.com, we're developing a REST API documentation generator for Java. In the process, we already generate a report that contains errors/warinigs in the code and the documentation (where it's missing). We're currently looking into expanding this towards a broader set of automated documentation quality and coverage checks.

Do you have any tips on current software that automates this (possibly not for REST APIs) or any articles that I should read?



I haven't used any documentation generators myself, so I can't properly recommend any. I did cover Socrata's API Foundry, which creates developer-ready API documentation from the client's dataset, which could be worth a look?