How to Write API Documentation Everyone Can Read Starting your API documentation can be a daunting task. Whether you’re learning the ropes for the first time, looking for a refresher course, or want to improve your existing docs, we’re here to share our best practices and tips for writing it, along with the pitfalls to avoid. Let’s get started 💪 The goal of API documentation 🌟 Before we jump into the brass tacks of how to write your API docs, let’s do a quick refresher on the basics: why creating fantastic documentation is worth the time and effort. The long and short of it is that you want people to build cool things with your product, and API documentation is what lets them do that. Your goal is to create docs that make that process as fast and easy as possible. The faster and easier your docs make that process, the better. When documentation is difficult to read or understand, hard to find and search through, or not maintained, the opposite happens: people are more likely to turn to an industry competitor for whatever integration or use case they’re working on. In addition to helping with developer adoption, good API documentation often has secondary benefits to other teams at your company. Sales and support are two examples. ReadMe customer DriveWealth previously struggled to keep their docs updated, which resulted in more support tickets, as customers would see and act on outdated information before the docs were fully updated. Akamai also found that better documentation made their sales team more effective, as their buyers are often highly technical and having clear, thorough documentation made them a more competitive option. Documenting your API: The basics ✍️ Ideally, you’re not starting from scratch (or, if you are starting from scratch, you’re creating the documentation in tandem with a development team building the API). But, either way, it’s very possible that you’re feeling overwhelmed while looking at a mountain of very dense information that needs to be pared down into easy to read tutorials. One option many teams take is using a tool like OpenAPI and Swagger to get a head start on their documents, and then build on those automatically generated documents as they have the bandwidth and as the API evolves. Whether you opt for OpenAPI,document your API manually, or use a combination of the two options (or something else!), follow these five steps to get started: Know your audience API docs might be primarily for developers, but not all developers have the same level of experience. On top of that, in many industries, it’s becoming increasingly common for people in other roles (ranging from regulation compliance teams to marketing analysts) to use APIs in their work. You should have a clear idea of who your users are and how their needs differ — both in the style of documentation they need, and what they specifically need from your product. Understand the API adoption journey Put yourself in the shoes of someone who is completely unfamiliar with your product. What’s the catalyst that made them look for (and find) your product? What problem are they solving? After they solve their initial problem, what’s the logical next step? By mapping out a user journey, you can both better understand your users, and also create an outline for your documentation. Edit (and edit again) No first draft is perfect, and it’s easy to miss obvious mistakes when you’ve been working on something nonstop. Make sure to take breaks, rest your eyes, and then come back to what you’ve written to review it. An easy trick to find confusing spots or unnecessarily long sentences is to read the docs out loud — if you’re stumbling over it when trying to say it, it’s likely to trip someone up as they’re reading it. Structure for skimmability Even if the content itself is good, people are likely to stop reading if it’s all one massive block of text, without any clear hierarchy of information. Aim to create short paragraphs, bold important information, use numbered and/or bulleted lists when it makes sense, and have clear headers and subheaders to break up the text. Peer review Despite your best efforts, you’ll probably miss something. Set up a peer review system where teammates read your documentation, test out your coding samples, and work through your tutorials. You’ll be glad you had a second pair of eyes to examine your docs before releasing them to the public. Pitfalls to avoid 🚫 On the other hand, here are a few common mistakes that might not ruin your API documentation, but can make them Assuming a specific level of technical knowledge As mentioned above, working with APIs used to fall squarely under the purview of developers and software engineers, and be of very little interest to people in other roles — but that’s no longer the case. People in all kinds of roles, with all kinds of backgrounds, use API documentation every day. The specifics of those roles and backgrounds will vary depending on all the details of your product and API, but the takeaway is to make your documentation as simple and easy to read as possible, and to avoid making assumptions about what your readers do/don’t know. Assuming console access Depending on your product, industry, and other factors, the developers interacting with your API documentation may be contractors without console access (or not have console access for other reasons). If that’s the case, then they’re relying solely on your docs to build integrations — this highlights another reason that it’s important to create easy-to-use, thorough documentation and keep it updated. Not reusing content Your goal is to give a developer (or whoever is reading your docs) everything they need to solve their problem, on the same page, whenever possible. If you have a list of answers that address common scenarios, questions, additional context that’s needed for common use-cases, etc., then you can re-use that content whenever it’s relevant. Why reinvent the wheel? People are much less likely to get annoyed at having too much (useful) information than they are to get annoyed at having to open five new tabs to understand a single guide in your documentation. (This is exactly why we created Reusable Content blocks!) Under-linking Sometimes, giving context for a particular issue/use-case/etc. would involve adding a lot of content to the page you’re working on. If you don’t want to re-use a 500-word block of content (which is understandable!), make sure that you share at least a few sentences to orient the reader, and link to the page that does have more context. Technical writers may err on the side of providing less links, not wanting to overwhelm the end user, but your goal should be to avoid forcing someone to go hunting for more information. Not reviewing metrics or user feedback You should always be seeking to improve your docs over time, and two great, data-based ways to do so are by looking at your metrics and by actively seeking and incorporating user feedback. If people are regularly searching for a keyword that doesn’t turn up any results, it’s time to write some documentation that will turn up for that search. If the support team gets the same question, over and over, about the same part of the documentation, then it’s time to review and update that guide. Fundamental components of API documentation 🌟 There are plenty of ways to provide API guidance to your end-users: topical guides, tutorials, and support forums, to name a few. No matter what you go with, there should always be these essential sections in your docs: Quick start guide: Developers often learn by doing, and at least some of them will want to jump into using your API head first. Having a quick start guide gives them a place to do that, without making them sift aimlessly through your docs in search of a starting point. (Head here to learn more about what creates a good quick start guide!) Authentication: Each API handles authentication differently, so it’s vital to describe how your API does authentication upfront. Pretend you’re a new developer and showcase the authentication process in detail, from initializing API keys to how to send them in your API requests, and anything else they might need to know. Error messages: Listing out every possible error message is thorough, but not particularly useful. Providing background on your errors and how to troubleshoot once one occurs is much more practical. (Learn more about how to write good API errors here!) Endpoints: Help your users understand the best use cases for each endpoint and/or set of endpoints. The same use case might have multiple ways to get the job done, so make sure to cover the differences between them and the pros and cons of each. The more specific, the better! Terms of use: Yes, unfortunately, you have to add in some legalese. If it helps, think of it as a formal way of letting developers know how to properly use your services. This is also a great place to talk about API rate limits and any other constraints they should keep in mind. Changelog: An API is never “finished,” so you need to establish a workflow for updating documentation as your API evolves. This keeps your docs fresh and shows developers that your API is getting the engineering attention it deserves. Glossary: It’s a good practice to have a glossary available somewhere on your docs, especially if there are any terms that are specific to your API, product, or industry. The same word can mean very different things in different industries, and whoever is reading the documentation might not be versed in those nuances. This can be a dedicated page in your developer hub, or a glossary feature that defines a word when you hover over it — whatever makes the most sense for your API. Successful API calls ☎️ In addition to the fundamentals, you’ll want to get specific about what users should expect from a successful API call. To ensure you’re not leaving them in the lurch, be sure to include: HTTP status code and message examples: Every error message should be documented alongside its HTTP status code, and the messages themselves should include detailed stack trace information and details on fixing the issue. Request parameter examples: Even if your API is extremely intuitive, providing request examples is always a good idea. Beyond explaining what each parameter does, give a real-life example for each one, so it’s crystal-clear what the API expects. Code samples and tutorials: Developers usually have an end goal in mind when they begin the API integration process. So why not put some code samples of the most common use cases front and center? Each sample should have detailed context for each step, as if you’re taking them on a live tour of your API. If you have the time, you can insert hints or tips on how to adjust the example to work for other related use cases. SDK examples: SDKs are a great way to abstract away the complexity of HTTP APIs. SDKs may include built-in types or other kinds of documentation, but that may only go so far. Be sure to reference relevant SDK examples so that users can build with your SDK successfully. Static vs interactive documentation: Think about buying a car — rather than just reading about it online, you want to give it a test drive. Developers also want to try before they “buy.” They want to know that your API works for their use case and won’t cause any major issues before proceeding with the integration. To ease their worries, give end-users a playground or sandbox they can use to test out responses to various endpoints without deploying real code. To sum up: 🧮 In a nutshell, your docs should: Make your developers’ lives easier Be easy to understand, regardless of technical background or expertise Incorporate common use-cases and real-world examples Showcase a sandbox or interactive elements Have terms of use and any limitations laid out very clearly And, over course, be overall easy to navigate, with skimmable content, clear content-focused navigation options, and an easy-to-access search feature. Now, go get started 💪 Outstanding API documentation is crucial for creating a stellar developer experience and improving API adoption. If developers hate (or even feel “meh”) about your docs, you’re limiting your API’s potential before you’ve even started. Word of mouth is always the best advertising, so why not create that for your API?