Writing Better API Documentation
Piece of writing that every programmer love and hate
Aah… API Documentation… A piece of writing that developers want to read but hate to write. But as a programmer, it is important to have the skill to write good documentation because it will reduce your tech debts and make other programmers (or users) life easier. The question is, what is the best practice of writing one?
Plan and write before Code
Planning is required for almost all things, including writing documentation. Before you go writing one, you need to know the user that will read your docs. If you know the audience, it will help you to decide the writing, structure, and design of the documentation.
After you know the audience, then you need to know their intention of visiting your docs. Understanding the purpose and scope of your docs will help you structure the docs in a manner that addresses their needs. After all, they are the ones that will read it.
Be Consistent and Do Not Include Jargons
When you are writing documentation or programs, it is important to maintain consistency across the documentation. You are technically still free to choose what certain things are named or be written, but if you are being too creative with it, it may lead to unnecessary confusion and make it harder for the reader to understand. The best practice for this point is to use standardized and universally accepted naming conventions and terminologies.
Also, you should reduce the use of technical or domain-based jargon as it may not be understood by all of your doc readers. If it is impossible to do, then you should sufficiently explain in the documentation to eliminate sections that are ambiguous or difficult to understand.
Make Your Code Explain Itself*
*if your code is open-source or will be read by other code maintainer
A good programmer is a programmer that can write code that explains itself. By writing a code this way, the need of reading separate documentation will be reduced significantly. If needed, you can add some inline comments to help your fellow code maintainer to understand how it is used. Refer to my other article that discusses how you should name your application’s variables and functions.
Write as if you are not a developer
Cited from the masterclass website, the first thing to be a good writer is one that is able to describe their ideas effectively with the reader. It allows you to reveal ideas without demanding extra effort from the reader. A good documentation writer also needs to be like that. Remember that reading documentation by default is already hard enough even without badly written or unclear documentation.
Show where to start
Some documentation is written with a step-by-step tutorial. But some don’t. API documentation is usually the biggest offender in this area. They are notorious for being too overwhelming and assuming that users have vast experience with APIs while the reality some don’t. With that said, at least the thing you can do is add the “Getting Started” section and it should be written with patience to get potential users.
Include fundamental sections
In 2019, SmartBear, the developer of Swagger, surveyed API developers and users. They asked then what docs features are considered the most important in the community. And here is what they found:
Examples. Usually presented as pieces of code that demonstrate basic usage of certain code. Interactive examples in this case are certainly better than static ones.
Status and Errors. The all possible status or errors of an endpoint. Whether it is standard status codes or those specific to your API. This is also may contain error messages from the API.
Authentication. Since most API Docs start with authentication and authorization. It should cover basic information on how to get an API Key, how to authenticate, and an explanation of authentication sensitivity.
HTTP Request. Providing web requests in HTTP is the bare minimum for documentation. It usually explains what methods to be used in the request whether it is GET, POST, PATCH, DELETE, or anything else.
Do not put your docs behind a paywall or registration!
To make your API accessible, never ever put your documentation under registration, or even worse a paywall. Documentation must be accessible to all users since even for your registered user, their developer may not have the same permission nor access as the one that bought or register the account.
Never ever abandon your docs!
The biggest and most offense of being a good documentation writer is to abandon your docs. Whether you forgot to update, failed to mark a feature as deprecated, and/or any other reasons that make you did not update your API documentation. Don’t do that since the lifeline of an API is its documentation. Outdated documentation means a harder time to maintain API and a harder time to use and/or consume your API.
Examples of Good Documentations
Here are 2 companies that I personally think nailed on how to make good documentation:
Mailchimp
Mailchimp has a quick start guide and API reference with a concise explanation of it. It also explains each field and what to fill so we did not need a different glossary to know what each field is for. Their UI is gorgeous too :)
Midtrans
For a payment gateway service, Midtrans is doing a good job on how to create proper API Docs for their user. While some response codes based on each bank may be separated and require additional search effort, they are doing a good job on explaining it.
Writing documentation is tiring and sucks. But once again, it is very important for you to write one since it will help you debug or maybe even use the program in the future. So, happy coding and writing documentation everyone!