APIs are widespread in the internet ecosystem. This article discusses why API documentation is so crucial and how you can become an API technical writer.
Internet applications are rarely standalone. They are connected to other applications offering different types of services. These behind-the-scenes applications are not always visible to the users. The building blocks of these interactions are APIs, or “Application programming interfaces.” Their number has grown tremendously in the past years, according to this analysis from ProgrammableWeb.
APIs enable communication between two systems:
- The first application provides a service. This application exposes its service on the internet through a technical interface: the API.
- The second application, the “client,” is interested in the service provided and will use the API to access it.
For example, the API can be an interface to a payment service. The second application can be an e-commerce store using this API to enable online payments for their customers.
Why Is API Documentation Key?
Software developers on the client side rely mainly on the technical documentation, describing how to code correctly the “calls” made to the API. Good quality API documentation is critical to ensure the adoption of the API by new clients and to make it easy to use. According to the 2021 “State of the API” report from Postman:
- Documentation is the fourth parameter taken into account when wanting to use an API.
- Documentation is the number one pain point when using an API.
So if you are a technical writer interested in breaking into the internet industry, writing API documentation is a fundamental skill to have.
How to Start
Firstly, you need to know the basics of technical writing. It includes the following skills:
- writing in a controlled and straightforward language,
- structuring documentation in a clear and meaningful manner,
- following standards such as applying a style guide or respecting a legal framework.
If you are not familiar with technical writing, following a course on this topic can be beneficial to get started. You can look into this free technical writing course by Google. This resource is an excellent introduction to writing for a software developer’s audience.
Then to become an API technical writer, you need to learn about the technology itself. The most popular type of API, called “REST,” is simple to get started with. To try out a REST API, you can use free tools easily accessible from a web browser. This extensive “Documenting API” course can guide you through the process.
Creating a portfolio to showcase your experience can benefit you when applying to API technical writer jobs. While you are learning, you can write samples of documentation. For this purpose, you can do the following:
- Write your own version of documentation of a publicly available API that you can test without being a paying customer.
- Contribute to an open-source project needing an API technical writer to create documentation.
If you want to go deeper and pursue an academic degree in technical writing, TCLoc online master’s program from Strasbourg University in France will spark your interest. You can learn more about the content of this career-oriented program on the curriculum page.
