How to Write Good API Documentation {Updated}

Your documentation is the best reference for programmers trying to implement your API. As you already know, the documentation can have a huge influence on user experience. The documentation describes what features and services your app offers, and allows developers to use them. 

Basically, the documentation offers developers a chance to become familiar with your product and get a first impression. Therefore, if you want to leave a good first impression on developers around the globe, you have to put some effort into your documentation.

Below, we have few things that will help you fine-tune your API documentation.

Figure out your target audience

Before you even start writing anything, you need to figure out who your target audience is. Knowing who exactly you’re addressing will guide your design, language, and structure decisions. In most cases, your documentation will be read by one of the following group of developers:

Internal developers

Some people tend to focus too much on their external audiences and forget about their own team members. You see, the internal team working on your API will use the documentation too. For instance, by explaining the endpoints of your API, you’ll easily avoid all of the “what-call-does-what” confusion. And that’s why API endpoint documentation is so important.

External developers

Developers who've used your API before will surely come back to your documentation to use it as reference material. These developers usually need small bits of information on some of the features your API offers. If this is your target audience, you need to structure your documentation in a comprehensible way to help them find everything quickly. 

Inexperienced developers

Last but not least, we have the developers who have little to no experience with your platform. In most cases, they need the most support. They require clear and concise content, sample code, and step-by-step tutorials in order to use your API. 

Carefully design the documentation

If you want your target audience to have an enjoyable user experience. Obviously, there’s no “one-fits-all” solution for API documentation; there are some things you can do to help users interact with the documentation and understand it more easily. 

Dynamic layout

Static layouts are not only mind-numbingly boring at times, but they are also inconvenient at times. A dynamic layout makes the navigation easier and allows programmers to look for specific phrases and topics. Also, starting with a dynamic layout will allow you to expand the document any time you want. 

Single-page layout

On the other hand, if your documentation isn't all that big, you should go with a single page layout. That allows programmers to have a look at the documentation structure at first glance. What’s more, a single page document makes it possible for programmers to use the search functionality of their browser. 

Multi-column layout

A two-column – or even a three-column – layout has the navigation on the left side of the document and code examples on the right side. This layout is perfect for newbie users because they make things a lot easier by showing examples and endpoints in context. 

Keep everything up-to-date

Most people aren't able to make their documentation perfect on the first try. Basically, if you want to get everything right, you should be ready for a couple of revisions. If your documentation is not up-to-date, most developers will become frustrated after a while. 

Outdated documentation can – and probably will – diminish all of the trust you managed to establish by putting a lot of work into it in the first place. Therefore, when maintaining your documentation, here a couple of things to keep in mind:

• Remove deprecated features: - You need to regularly revisit your documentation, look for deprecated features, and make an effort to explain why they’re deprecated. 
• Introduce new features: - You need to describe new features before the launch of your API and make sure you have enough time for the new content to go through the editorial process. 
• Get more feedback: - Every bit of feedback you get from analytics or support should be reflected in your documentation.

With that, we’re finally done. If you have any additional questions about API documentation, feel free to leave a comment in the comment section below.