Akamai has made leaps and bounds in its API documentation since its early days. Mike Sierra over at the Akamai Developers blog explains how they improved the accuracy and consistency of their API docs in recent years.
In the early days, developer teams were in charge of different parts of the documentation. The result was inconsistent usage of terminology across docs and out-of-date explanations because developers didn’t have the time to update in a timely manner. One of the early major changes Akamai instituted was putting technical writers in charge of documentation and devising (and sticking to) consistent editorial standards.
For greater accuracy and consistency of documentation the team made the decision to move to RAML as its API descriptor language. RAML was chosen over Apiary’s Blueprint markdown-based language because RAML can be parsed more easily as a data structure. This made validating content and syncing with source code much easier. Documentation can be generated from these RAML files, which also means API docs can be updated immediately in response to changes in endpoints, data objects etc.
As well as how documentation is generated, the team overhauled the docs interface. Originally, to find an API method, you had to select an API interface, find the endpoint you wanted and then choose the method on that endpoint. The new interface shows you the API operations you use first, with tabs for each operation to make different aspects of each method easily accessible.
One of the key tabs that’s changed since the early days is the data tab. In the early days, APIs often didn’t document data structures exchanged by APIs at all. You had to work that out yourself from sample data. Now, the team uses JSON schema to describe data structures. To avoid nasty JSON pointer expressions, data structures are explained with a more intuitive notation that uses expressions like ‘parent.child’ or ‘parent.children[n]’.
Mike concludes by emphasizing that the work is not over. The team’s looking to improve tools to better present aspects of the more complex data objects.