APIs, or Application Programming Interfaces, are the secret weapons of the web. APIs allow developers to create brand new systems, build off of existing programs, or refine and improve software without having to write new code for every function, action, or step they need to take.
As a technical writer, you don’t have to understand the in’s and out’s of everything that takes place inside an API. But you will need to understand enough of how the code functions in order to write clear, easy-to-understand API documentation that other developers can use to best utilize the code in their own projects.
So how do you digest the key points of an API and then create standalone documentation that works for future developers and other users? We’ve put together three steps below to get you started.
Step One: Talk to the API developers.
If you’ve been tasked with writing technical documentation for an API, chances are you also have access to the developers who have helped create, maintain, or improve the API. Ask them to walk you through the key functions that the API performs, how it integrates with other services and systems, and how developers from outside your organization can interface with the API to improve their own products, services, or software.
For example, let’s say you’re working on an API for a service that helps users find cheap hotel rooms. In all likelihood, developers from other web-based services may want to tap into your API to improve their search results or provide their users with valuable information. Understanding what systems they are currently using on their own back end can help you better determine how your own API works with others. With the help of your development team, you can anticipate questions before they get asked.
Step Two: If you’re still stuck, go back to the basics.
While developers are brilliant at their jobs, they aren’t always able to explain the more complex aspects of their work in layman’s terms. After all, that’s your specialty! If you still feel confused or need a refresher on how APIs work, there is a plethora of excellent resources on the web, from the Documenting APIs course and the Write The Docs guidebook to how-to guides from software developers like MuleSoft.
In addition to better understanding the behind-the-scenes complexity of the API, another key starting point when tackling API documentation is to consider how often the documentation will need to updated. Are you writing docs that will need to be changed every few months as the API evolves and changes, or are you writing the “bible” of your API, which will only see minor edits and alterations as new functionality is added? This will help determine your approach to the documentation moving forward, including how best to address those aspects of the system that are likely to change frequently.
Step Three: Use web-based tools to help.
Writing technical documentation for an API can be an incredibly rewarding process, as you’re helping other developers find new and unexpected uses for the code. But it can also be grueling, often requiring extensive reviews, edits, and updates.
You can help simplify this process slightly through the use of web-based tools that have been designed to make documentation easier. These include systems like Postman, which helps automatically generate code documentation for you, and Github, which helps you present well-written documentation in a clean and accessible format.
Getting started writing API documentation can feel daunting, but with support from your development team and the resources mentioned above, you can get started right away.