I would like to share my experience in writing API documentation with you. Probably, many of you are wondering what this mysterious API is and what it is used for. Well, there are different types of API, however, in this article I want to focus only on a Web API.
You’re probably wondering why this is a task for a technical writer and not an architect or developer? It’s a way to effectively support a project team, whose members can focus on other activities, such as writing a code or improving its quality at the same time.
Let me start by explaining what this seemingly familiar acronym stands for. An API stands for an application programming interface. It can be described as a kind of middleware. It uses a certain set of rules and protocols by which two or more applications or programs can communicate to exchange data. I’m guessing this still doesn’t tell you anything.
Let me use an interesting analogy that I have come across recently. Imagine you are in a restaurant and want to order a meal. You read the menu. Next, the waiter takes your order and passes it to the chef, who prepares the meal. When your dish is ready, the chef gives it to the waiter, and the waiter brings it to your table.
You could say that an API plays the role of a waiter. As a user or an application, you send a query, which is placing an order. The waiter representing an API takes your order and sends it to a chef, that is, a server. In response, a server takes the appropriate action and, through an API (that is, a waiter), sends its response back. In other words, an API is a messenger that receives a query, translates it, and returns the right answer.
Source: What is API ? – DEV Community
You’d be surprised how often you use different APIs without realizing it at all. You do it when you access a website in your browser, publish a post on your social media profile, log in to your bank, or manage your shopping list in an online store.
We already know what an API is and how it works. The next question is: who should read API documentation and why is it necessary?
There is a growing number of cloud-based applications as well as applications that support mobile device users. To exchange data efficiently, service providers use APIs. This allows them to deliver services and software of better quality to their end users. By using APIs that someone has previously designed, service providers do not have to develop their product from scratch and can offer additional functionalities to their customers.
The increased demand for APIs entails the need to provide appropriate documentation that accurately describes their functionalities. Providing it is well-prepared, it ensures a positive perception of a product by a customer, helps build trust among potential business partners, and enhances user experience.
As for who API documentation is intended for, it is primarily aimed at stakeholders and decision-makers in a company, as well as developers.
For stakeholders and decision-makers, such documentation can be useful in assessing the business value of a given API through sample use cases that can illustrate why they should use that particular API in their product. Also, they can find it helpful in assessing the usefulness of a given product to achieve their business goals.
For developers, API documentation is the main source of information on how to communicate with a given API. When using it, a developer should easily find information about the authorization and authentication protocols that expose a given API endpoint (which is usually expressed as a URL) and sample scenarios illustrating common use cases.
Before I get into more details, I want to emphasize that a technical writer does not design an API – this is what a solution architect or developer does. However, since a technical writer is a part of a development team, they support developers in documenting a designed API by using appropriate tools.
At the very beginning, a technical writer is informed by a business analyst about the need to write API documentation for a customer. To do this, a business analyst arranges a meeting with a technical writer and a person who designed a given API. The architects and developers as designers of a given API know best how it works. Therefore, they are the main source of information about it for a technical writer.
During the first meeting, a technical writer should gather as much information as possible about a given API, including the following:
- the workflow of a given API,
- requirements to connect to an API,
- the most important elements to describe first,
- sample data sent or received in a given request,
- a type of tool to create documentation,
- the target format of the publication-ready documentation (a PDF file or website).
- It is beneficial for a development team to provide a technical writer with the workflow of the API in the form of graphical representations. Such visual elements can help a technical writer to illustrate the functioning of the API.
Moreover, if the meeting is held as a video conference, it is a good idea to record it (provided that all the participants agree to it). Such a recording can be of great help when writing API documentation as it is possible to go back to all the information and issues raised.
As soon as a technical writer gathers all the necessary information and analyzes it, they can start writing the initial version of the documentation. While working on it, they must keep in mind that the documentation should meet the requirements agreed with the development team. Here, I have to admit that while working on the first version, I happened to return to an architect with additional questions if something was still not clear to me or some information was missing. If it was a minor issue, I would contact the architect via chat. To clarify larger ambiguities, I tried to arrange an additional meeting at a mutually convenient time. At this point, it is also worth asking for the help of a testing team to test API queries, for example, by using Postman (if a technical writer can’t test it by themselves on a proper testing tool or environment). In addition, a testing team can help with the screenshots of the system so that they can be included in the documentation.
Once a technical writer completes the first version of the documentation, they can give it to the development team for review to identify any mistakes and inaccuracies. At this point, the documentation should be tested for usability, that is, whether it is easy to understand and use and whether all the navigation elements and links work properly. Ideally, such a test should be carried out by end users, possibly by usability experts, to ensure that the documentation fulfils the established requirements.
Once corrections are made, and the documentation meets all the requirements, a product manager or project team leader approves it for publication.
The process of writing API documentation seems long, however, it does not end there. It is also important to easily maintain the documentation and its versioning, which is possible with the help of a suitable content management tool. This way, we can be sure that the documentation is always up-to-date.
I hope you now have some more insight into the concept of APIs and the technical aspects of how a technical writer creates API documentation (which, as you surely know, is just one of their many tasks). This is not the work of one person but a joint effort of many people, which is why close cooperation between a technical writer and an entire development team is so important. Architects and developers are not only the main source of knowledge about a given system but also invaluable reviewers of the documentation written by technical writers, as they can identify all substantive errors.
This article does not exhaust the topic – it is only an introduction to it. I invite you to read its second part, where I focus more on API documentation itself as well as its structure.
- Desai, Vraj (August 31, 2021). What is API? [a blog article].
- International Technical Communication Qualifications Foundation (June 17, 2020). Syllabus – Technical Communication Professional Foundation Level [a PDF file].
- Lutkevich, Ben (no date). application programming interface (API) [a blog article].
- Technical Writer•Business Analysis & Technical Writing
She is a Certified Technical Writer with two years of professional experience. She has been involved in writing user guides, release notes, and API documentation for customers in the Life Sciences sector. In her spare time, she enjoys hiking, climbing via ferratas, and evenings with a good book.