Developers are a fickle bunch. If you don’t give them what they’re looking for, with a minimum of fuss, they’re likely to look elsewhere. Programmers don’t want to spend an hour installing tooling — they want to quickly check if a tool meets their needs and fits in their existing stack and workflow.

You wouldn’t sell a piece of furniture without assembly directions and a manual. Imagine what a nightmare assembling a bookshelf or coffee table at home would be if the instructions were jumbled and convoluted. Similarly, quality API documentation is vital to ensure a positive developer experience. It’s like a user manual and assembly instructions in one file.

To help you put together the best API documentation, we’ve organized some best practices to consider. Following these tips should help you provide API documentation with a world-class developer experience.

1. Consider the Developer Journey

To start, it really should be called developer experiences, as the experience a developer has with your API has multiple phases and components. Keeping this in mind and structuring your API documentation accordingly is an excellent place to start.

You can break the developer journey down into five stages:

1. Onboarding
2. Gathering Requirements
3. Design
4. Build
5. Maintenance

Onboarding is everything a developer needs to get started with your API. You might think of it as the Readme.md file in GitHub or the landing page of a product. Once the API is installed, developers confer with the team leaders to see how the API will be used in the Gathering Requirements stage. Then the coding begins in earnest during the Design and Build stages. Finally, once an API is integrated into their stack, Maintenance is everything.

Check out Twilio’s API documentation for a good example of how the developer journey can be addressed in the structure of the API documentation itself. The Get started and How to set up your local development environment are both good examples of Onboarding. It’s good to answer basic questions developers might have about the service and provide some quick and easy demos so they can get a brief glimpse of it in action.

The remaining sections cover more advanced concepts and show users how to maintain the API, covering the Design, Build, and Maintain stages of the developer journey. Following the developer’s journey provides a good template for organizing your API documentation by complexity, beginning with the most obvious information and drilling down into more advanced uses as you go.

2. Follow a Predictable Format

When creating API documentation, you don’t need to reinvent the wheel. This is one area in tech where the known and the familiar are advantageous. When creating your API documentation, it’s a developer experience best practice to follow a predictable format. There’s a reason the three-column layout is so common and so popular.

One of API documentation’s main jobs is to remove as much uncertainty and confusion as possible when a developer first starts using your API. You want it to be as smooth and seamless as possible.

3. Include a Self-Serve Playground

One thing to remember with API documentation best practices is that new users are going to make up the bulk of your audience, as they’ll be pouring over the documents to learn how to get started. One of the most worthwhile best practices for API documentation to keep in mind is to pay special attention to the Onboarding phase. You want to offer as few limitations as possible during this stage, as there’s very little to prevent a new user from jumping ship at this stage.

Offering a self-service playground for your API lets users audition your API even before signing up for an account. This can be implemented with a simple demo using a site like GitHub Pages or Codepen, like this demo for Fetch API. If you’re looking for a slightly flashier option to make more of an impression, you could implement a self-serve API option at a dedicated web page like this one at Dolby.

4. Consider Popular Languages

The best API documentation includes code snippets and real-world examples, which give users everything they need to simply cut-and-paste code into their development environment and get some results. Including code snippets for the most popular programming languages is one of the most universal best practices for API documentation, as you can’t ever really go wrong with including too many concrete examples or details.

If you really want to fine-tune your API documentation, you can dig even deeper with your users to find out specifically what languages they’re using. You might offer a beta version of your API before fully going live to gain some additional insights into API usage, for example. You might discover that your users really love consuming your API in Rust, for instance. Therefore, including examples of API implementations in Rust would remove one more point of resistance between a new user and a dedicated customer.

5. Follow An API Specification

API documentation tools usually follow popular standardized API specifications to generate the documentation. And automated API documentation generators are pretty prevalent in 2023.

This is one of many reasons why following an API specification is a good idea. Not only can it deliver an improved developer experience, but it also saves you time and effort down the line. Automated API documentation generation also ensures your documentation is always up-to-date, as any changes you make to your API will automatically be reflected in the documentation. Following an API specification also helps ensure your API is searchable and discoverable.

Numerous popular API specifications are available, but OpenAPI is generally the most popular and widely used. It’s not the only API specification around, though. Some other API specifications include:

• JSON:API
• OData
• AsyncAPI
• GraphQL Schema
• RAML
• API Blueprint
• JSON Schema

Consider investigating the differences between these API specifications to see which one best suits your needs.

6. Create a Postman Collection

Postman is one of the most popular platforms for testing and consuming APIs, with over 25 million registered users. Postman Collections are a brilliant way to implement your API documentation, as they’re easy to share between users. They also let you save requests or actions, which can also be searched as well as seen in your history.

Postman Collections are also searchable if they’re available to the public. This essentially makes it an API search engine, and a popular one at that. Creating a Postman Collection for your API is definitely a recommended API documentation best practice if you’re serious about building your audience and widening your user base.

7. Practice Consistent Naming Conventions

One essential principle of Roy Fielding’s REST Dissertation is that an API should be self-descriptive as often as possible. You should make as many aspects of your API as apparent as possible, so users won’t have to go to an external resource to learn how to use your API.

Sticking to one naming convention across your entire API (or APIs, if you have more than one) and all of your API documentation is a great best practice to keep in mind. For example, it’s recommended to follow camel case conventions, with the first word lowercase and each subsequent word capitalized, like getUsers, for example. Another practice is to use the plural case for categories and groups and singular for individual resources.

Final Thoughts on Improving Documentation Developer Experience

Remember, your API documentation is sometimes the first interaction point with a new user. Even if it’s not, it will likely come early in the developer journey. Documentation is one of the first and most important steps in converting curious users into loyal audiences.

API documentation also offers a unique opportunity to talk to users in simple, easily-understandable terms. It’s a chance to show developers how to use your API and what it can do in a straightforward, everyday language. Following these seven steps will get you thinking from the perspective of your users and how they’ll use your API, which is one of the most important aspects of improving your developer experience.