By Abhilash | July 21, 2019
When creating API for consumption by third party developers it is always important to document them. The task of creating API documentation may not be trivial but its fairly doable considering the tools available but the task of maintaining them seems to where the product teams fall short more often than not.
All seems perfect at the launch of version 1 of the API with neat and clear documentation complementing the efficient API’s that you have so arduously built. As soon as your API service starts to get traction there arrive requests for changes, additional features etc, and they start queuing up your task pipeline so much so that more often than not updating the documentation, which is still at v1 while the actual API is ever-changing, seems to become the last item on the list that never gets looked into.
Until one day when a new customer of your API asks for the documentation to get up to speed with the API and you have to sheepishly come up with one reason after another to hide the fact that there exists nothing that would make sense and also maybe go through the additional pain and effort of guiding them.
Having gone through something similar, the team that I worked with decided that enough was enough and that we needed to find a way to keep the documentation updated. One of the important design decisions was to aim for a solution which was entirely automated, given the pace at which our API was evolving and, considering the important fact that “devs will be devs,” that they hate documentation and anything which is not a part of what they already do. That’s when the need to make documentation a part of the dev workflow started taking shape. We evaluated several options before opting the below design.
At a high level the idea is that since we have a practice of writing code comments all we needed to do was to generate documentation from those comments and ensure with subsequent code change, via code reviews, that the comments too gets updated, and this would have the dual incentive for devs of making the code more readable and also ensure that the documentation stays updated while adding very little extra effort to the existing workflow. Since the documentation that got generated needed to be easily browseable, visually renderable via third party tooling, and later support code generation for clients, we opted for Open API which meets all these requirements.
Once we generate Open API Spec(which is a json file based on Open API syntax) we needed a way to visually render and host it along with several other additional tutorial pages. That was where the Open API import feature provided by readme.io came in handy. “Readme” in their own words is an easy to use tool to help build out documentation.
So to summarize, In order to overcome the pain of maintaining API documentation we decided to automate the whole process while keeping a tab on the additional effort required off devs by generating documentation from code comments which conform to an open standard such as Open API and then used the readme.io service which consumes the open API spec to visually render the documentation. Additionally, all of these steps are part of the build pipeline so that on each deploy of a newer version of the API, the documentation gets updated almost near real-time.
So this was the first post in a series to explain at a high level the problem of maintaining documentation and its solution, subsequent posts would detail out the solution and maybe some alternatives as well.