Search
Online Courses
Pocket Guides
Last Update: 10.11.2017. By Jens in APIs | API Business
Documenting your API is extremely important. Without documentation, nobody, not your product owner, devs or your customers know what your API does and how to use it. In this article series, we will take a look at common ways of documenting, their advantages and disadvantages and explore different solutions.
In the first part, we will cover what role documentation plays and three common ways of documenting an API.
A documentation usually serves different audiences and thus has to fulfill various expectations. Each audience is looking for a slightly different aspect of the same information. A developer of the API is often not interested in the tech details of the API and how they are implemented. A developer using the API is interested in how to solve his given business cases and thus need to know the business functionality and how to access the technical side of the API.
Other audiences are the business responsible involved, either as the provider or a consumer. They are purely interested to know their uses cases are fulfilled.
However, not all audiences are necessarily involved in every documentation, and sometimes a participant is part of more than one audience.
The documentation should contain enough information for each audience involved, so their questions are answered and know how to use it. However, that depends a lot on the type of API you are providing. In an internal API, you can take shortcuts and use domain and company-specific terms or assume domain-specific knowledge. Whereas in a public API facing the masses, you will have to write differently and simpler. Documentation for open APIs for selected third parties, I call them protected APIs, are somewhere between the other two types.
For example, if you are a publisher and provide an internal API you can use all industry-specific terms without further explanation. However, if you open up the API to customers, you might need to add a dictionary of terms, etc. so your customers coming from a different industry understand it.
To sum it up, a consumer must be able to understand if your API solves their problem and how to use it technically. If your documentation solves that, you usually get way fewer support requests and set up new customers is a breeze. On the other hand, if it is already a nightmare to set up a new customer, your documentation probably sucks.
There are three common ways for documentation and like everything in life they all come with tradeoffs. The first one is to write the documentation completely separated from any implementation. The second one is to document close to the implementation aka code, and the third one is a mix of those two.
In this type, the documentation is maintained in its own place, often in Word, and completely independent of the implantations and any release cycles.
Advantages
A significant advantage here is that someone else than an expensive developer can maintain the documentation. Not utterly alone because it must contain technical details. But overall, it can do someone else with a bit of help from a dev.
If one needs to expand explanations, etc., it can be done without any devs involved, and you can update the documentation at will.
Disadvantages
This type has two disadvantages.
First, it has a high chance of becoming outdated, and the information in the docs do not match the actual implementation anymore. This will lead to frustrated consumers and possible errors. However, you can manage that by making it an absolute deliverable of each code change.
This is where the second point steps in. You always have to maintain technical information in two places. In the implementation and in the documentation. In addition to the previous solution, you must allot enough time for these tasks.
The next way is to create the documentation out of the actual implementation. Meaning, the developers usually write the documentation inside the code and on build or deploy time, the documentation is created by extracting the information from the code base.
Advantages
The big advantages are that the documentation is almost always up to date and matching the actual implementation. At least, regarding the technical aspects of the API.
Disadvantages
Your expensive devs must write the documentation entirely and not only the tech part. Whenever an update is needed for ordinary text or terms, a dev must change it the code. Now, depending on your deployment cycle, it might take a while before the documentation is available for your consumers.
Another disadvantage of the approach is that ordinary text and term definitions are a nightmare to write in or close to the code. Many solutions also get painful when writing longer explanations with multiple paragraphs, etc.
The last category is a mix of the other two. In this, documentation is split into two main parts - technical information and the additional business information.
Advantages
The big advantage is that the technical aspect of the documentation is described pretty close to the actual implementation again. The rest is also, mostly, pretty close to the code base, but in a way that someone else could maintain it. So the docs are up to date.
Disadvantages The mix has a few disadvantages. First, in typical tech stacks, the additional text is also kept in the same version control system the devs use. Therefore a responsible person must be comfortable working with a version control system and still be trusted to not mess up anything else. Or, you need to create a custom solution and put the non-tech maintained info into its own place. However, be aware that your organization must be able and commit to maintaining these.
Second, this solution might not be available for all tech stocks so it might not work for you. Also bringing in new tools for everything starts to make thing getting too complicated.
There is no clear right or wrong. It depends on your situation, your audience, the purpose of your API, your team, etc. If it is an internal API, it might be enough and work great for you when the docs are maintained at the code base. This still works, if you extend it to a protected API and the change cycle has a pretty low frequency. However, if it is the first try for a single consumer, a simple separate file like Word, might be fine.
When you evaluate it, also consider the frequency of API changes. Is it a one-shot test or is it already foreseeable to release weekly updates? Additionally, if you already have an API, talk with your customer support team, they might provide valuable insights in consumer questions and problems. Then consider these findings when making your decision.
Starting with the next article of the series, we will explore a few (almost) standard solutions for describing APIs which fall in one of the three categories above. Next is API Blueprint