What is API Documentation?
Application programming interfaces, or APIs, are a collaborative process. Developers build a platform that can be accessed via endpoints, and developers use the endpoints in their own development processes. Documentation fills an important role in this process. Well-written software documentation will be self-serve, instructing developers how to unlock an API's functionality without requiring the API developer's time for questions. The usually onerous task of documenting endpoints can be automated, too. Documentation is usually delivered on the API company's website, or in a Markdown file with the code itself (in a GitHub repo, for example), if using the docs as code approach. Documentation counts as a technical deliverable, so besides being reader-centric and helpful, it must be technically correct.
Why document APIs?
The way software is consumed (and monetized) has changed drastically since the rise of REST APIs. Instead of buying a box of software with a manual, a company may choose to adopt an API solution (i.e., purchase access, or use an open source solution), and this adoption is usually led by the software development team. How does a developer discover, use, and adopt this API? Why do they choose one API design, and not the other?
Imagine there are two identical APIs on the market, and a developer tries them out to solve a problem. The first API has poor, thrown-together documentation, and the developer struggles to call the API's endpoints. The other API has great documentation, maybe some interactive tutorials, code samples, and use cases, and the developer is up and running in no time. Most importantly, the developer quickly finds that this API can solve the problem they're facing. The first API could have solved the same problem eventually, but it took too long to get there!
You can have the best, most functional product, but no one will use it if they don't know how. This is why API docs are so powerful, especially when software is found, consumed, and shared online.
Popular documentation platforms
Documenting APIs used to require manually testing and documenting every single endpoint. The Open API spec has cut down significantly on this process, but it's not the only option available to developers producing web APIs.
Swagger / Open API
Swagger can take any API and generate Open API spec documentation with the push of a button. A writer will still write an API description to describe what the endpoints do, and how to interact with the product, but the standardization of Open API Spec allows automation to save time.
ReadMe
ReadMe is another popular documentation product. Its WYSIWYG editor is intuitive and easy to use for anyone who's used Google Sites. It can also take API documentation, and has writers build "recipes" to guide readers on tasks.
Static Sites
Static sites built with tools like Gatsby or Jekyll and written in Markdown language are lightweight, fast, and easy to create. These have proven popular for documentation also, because of their ease of use and low cost. If your product really just needs to list terminal commands and endpoints to get developers engaged, static sites are the way to go.
Conclusion
Documentation used to be a bit of an afterthought in software, but now it's become a key part of the developer experience. It's no longer just a way to tell people how to install your program- it's become a key part of marketing, sales, and customer satisfaction.
