Approaching API documentation for the first time can be quite scary.
After all, this is documentation written for developers, so technical writers really need to know their stuff if they want to provide this audience with valuable and usable information.
Have no fear, though. We’ve broken the entire process down into seven easy-to-follow steps that will help you efficiently write API documentation, no matter how complex it gets.
Let’s dive right in with the first step: thorough preparation.
Step 1: Prepare for API Documentation Development
API documentation development should always start with an inventory of the resources you will be utilizing for the writing process.
In a nutshell, these resources can be divided into a couple of categories:
- Audiences
- Subject Matter Experts (SMEs)
- The API itself
As far as audiences are concerned, you should be aware that two kinds of experts will be looking at your API documentation:
- Implementation specialists
- Developers
According to Joanna Suau, a developer educator and technical writer at Infobip, implementation specialists will be looking for a good fit between your API and the project they’re working on:
They will probably turn to the API reference for assessment. So, a bit of conceptual information, like the most common scenarios you’d use the API for, and a process workflow will go a long way in advertising the API and showcasing its potential.
The other kind of audience are the developers who will actually implement the API into their own workflow.
This means that, as a part of your audience research, it would benefit you to check out some of the products that may benefit from your API and come up with use cases in instructions tailored to their needs to later use in your documentation.
As for the human resources you’ll need, your subject matter experts, it’s important to get in touch with the people that worked on the API and interview them to find out everything you need to know about the product.
Let’s look to the experts for some smart questions to ask. Here’s a technical writer’s go-to set of questions when they’re talking to SMEs about their project:
As you’re completing your preparations, don’t forget to also access the API yourself and explore it to see how it ticks.
After all, no writer can produce quality documentation without ever trying out the product for themself.
Some of the elements that could help you understand the building blocks of the API are the design files, the API blueprint, and the API key.
Here’s a quick screenshot of an API blueprint just to show you the syntax and how descriptive this resource can be.
Remember, good preparation is half the battle where documentation is concerned, so give enough attention to this first step and the API documentation will practically write itself later.
Step 2: Decide on the Writing Style
This phase of the API documentation writing process is quite similar to the corresponding phase of the document development life cycle (DDLC) for technical documentation meaning we can extract some universal rules here.
The first is to decide on a technical writing style guide that’s going to guide the creation of all subsequent API documentation at your company or on this project.
A style guide will help you keep your writing consistent and give you some great pointers on how to keep the textual parts of your documentation accurate, on-topic, and as useful as possible for your users.
If you don’t have a house style specific for your company, feel free to use one of the many style guides available to writers online or in print.
For example, you can use the exhaustive and extremely helpful Microsoft Writing Style Guide.
You’ll also want a reference to keep your naming conventions as consistent as possible.
That’s important because users may get confused if you’re using multiple terms to mean the same thing.
You can use the Word List section of Google’s Style Guide for this purpose as it has the most exhaustive list of naming rules we’ve encountered and caters to technical writers using developer jargon in their work.
Last but not least, you should also decide on the format your API documentation is going to be presented in.
There are a few formats to choose from, and a very popular one is the three-column approach, like in Stripe’s API documentation.
The table of contents is situated on the left-hand side for easy navigation, with the description in the middle and the code samples on the right to make it easier for users to follow along with the explanation.
Once you choose your writing style, it’s imperative that you stick to it from the beginning to end or else your document might appear chaotic and badly organized, which can do some serious harm to the user experience of the documentation.
Step 3: Add the Key Elements to Your Document Structure
Before you start reading this chapter, make sure you also read our blog about elements no API document should be without.
Now that you have enough information about the API and an established framework for your documentation, it’s time to start thinking about the kinds of content you’re going to be filling it with.
A good practice to follow here is to focus on coming up with common use cases for your API and then creating documents around them.
This is an excellent approach because interested parties accessing your documentation will probably already have an application in mind, seeking solutions that fit their ideas perfectly.
The API for Google Maps does this very well. Its documentation is divided into guides that explain how to achieve certain tasks with the API once it’s integrated into the product.
For example, if you need to display a static map on your website, there’s an article explaining how to apply the API to do exactly that.
After you’ve covered all your use cases, the next step is to provide a starting point for your users who are approaching the API for the first time.
APIs are complex products and working with them can become chaotic fairly quickly so it’s great to start users off with an introduction to the API and a guide on how it works.
Again, Google Maps’ API leads by example.
The documentation gives incoming developers all the theory and practical exercises they need to get their bearings and have a great first experience with the API.
The final key element you need to complete this phase is an outline for your documentation.
An outline will help guide your writing and make your job much easier, so try to be as detailed as possible and see if you can come up with a document outline you can replicate for most of the documents in your base.
For example, Spotify’s API documentation follows a successful formula in many of its articles.
The outlines for the articles cover the universal basics, such as Installation, Responses, Error Codes, and Authentication.
The information covered here gives the developer the entire set of tools needed to successfully work with the API.
The better you cover your bases in this phase, the easier your job will be once you actually sit down to write the documents, which is the next phase in this process.
Step 4: Develop the Content
This step represents the bulk of the API documentation writing process.
In the content development phase, all the preparations you’ve made will help you write consistent, accurate content that’s actually useful to developers working with the API.
The exception of API documentation is that the content you’re developing needs to be two-fold.
The first part are the descriptions, explanations, and textual guides you will be writing to lead the user through using the API.
After all, you’re writing for human beings, meaning you’re going to have to provide quality, engaging content that will help them understand your product and use it successfully.
Here, you’ll need to use some of the best practices of technical writing.
Have a look at Twitter’s API documentation.
It’s an outstanding example of developer content that goes above and beyond by making the API seem user-friendly and introducing developers to a whole world of possibilities.
To follow Twitter’s great example, you just need to remind yourself that you’re writing for people and use conversational language to get your points across easily.
Do your best to motivate your readers by providing them with ideas on how to use the API to build new and exciting things.
On occasion, you can even use humor to lighten the mood, as GitHub does in its documentation:
The other part of your documentation will be the code you’ll be adding to illustrate your writing and make it useful and actionable for developers.
This part of any API document consists of code samples and examples that show, rather than tell, the user how a particular feature of the API works.
You might want to present code in parallel to your descriptions and guides so that developers can instantly see how something works, instead of just reading about it.
That’s how Stripe’s API documentation does it, and Stripe is widely regarded as one of the best-designed API documentation spaces available today.
With the clean, sleek look of the documentation, it’s easy to see why.
Every section of the documentation has a corresponding code snippet representing the request and response on the right-hand side. This makes the documentation particularly easy to use.
To conclude, it’s clear that developing the content for API documentation relies on two factors:
accurate and engaging copy written by a skillful writer and code snippets that support that writing in the form of samples and examples that make that content instantly actionable and approachable to developers.
Step 5: Review the Content
Once your draft of an API document is finished, it’s not a good idea to publish it until it has been thoroughly reviewed and tested.
Content review is a very serious matter and it should be approached systematically for the best results.
At this point of the process, your responsibility as the author of the documentation is to see that the documents receive the attention they deserve.
But first, it’s not a bad idea to give the document a once-over yourself to check if the documentation reads like it’s supposed to and that the content you’ve written doesn’t contain any glaring mistakes.
Here's an example of the most frequent mistakes to avoid in API documentation.
For this purpose, you can enlist the help of editing tools, such as Grammarly to make sure your writing is accurate, concise, and engaging.
After that, a logical next step is to get some SMEs from the company to look at the documentation and see if it’s accurate.
Ideally, this means involving the experts who worked on the API and therefore know its ins and outs.
This step can be quite tricky as developers are busy people, so try to avoid requesting reviews over email as these can get buried and forgotten quite quickly.
Instead, you could try establishing a Slack channel dedicated to SME reviews and invite your desired reviewers to join.
This way, you can actively collaborate on the review process and send reminders to move things along if need be.
Your SMEs should focus on the code given in the document and check if all of the requests, responses, authentications, methods, and examples are in order.
Finally, your document needs to be tested to confirm that it can help users achieve the goals it sets out for itself.
It’s best to approach someone who wasn’t directly involved with the API project for this task. Perhaps a developer or IT expert working on a different project at the company.
You can ask this person to follow the guidelines in the document to see if the document helps them complete the relevant tasks without problems.
They should focus on any steps missing or instructions that aren’t clear enough to follow and provide you with detailed feedback.
And with testing completed, you should have a valuable document on your hands that guides users through the API and helps them integrate it into their own product without a hitch.
Step 6: Publish Your API Docs
When your documentation is ready to be published, the only thing left to decide is who should have access to it.
In this regard, API documentation can be divided into two groups: public and private API documentation.
The former is the documentation you want to share with any interested user online.
This kind of documentation is usually published on the company’s main website or a dedicated documentation website, like in the example below.
Many documentation providers create their documentation spaces using specialized software that offers server space and publishing capabilities.
Documentation software, like Archbee, allows users to directly publish branded API documentation to their own domain that’s hosted on Archbee’s system through AWS's CloudFront content delivery network.
That means that every documentation website created with Archbee is lightning fast and reliably accessible.
So, if you want to make your API documents publicly available, just click “Publish” once the documents are verified and authorized by the appropriate people.
If you’re using documentation software, the documents will instantly be available on your docs site.
On the other hand, if you don’t want to put all of that information online, you can keep documents in your collection and only share them when needed.
The easiest way to do that is, again, through your documentation software.
For example, Archbee has a Magic Link feature that allows you to authorize a third party to view the document simply by providing their email address.
As you can see, there’s a lot to consider even after the document has been written and reviewed.
However, such choices are made much easier with some good documentation software.
Step 7: Maintain the Documentation
A good technical writer knows that they are never really done and finished with a published document.
In other words, when a document is live, you shouldn’t forget to maintain it and keep it updated as your API evolves and changes.
If you’re part of the technical writing team that’s continually working on the API, you might be involved in writing the updates for it.
Therefore, a sound practice to follow is to update the relevant documents as soon as a new update or product version goes live.
You can also use alarms and notifications to let you, or another stakeholder at the company, know that a document needs revising.
Archbee has a verification feature that lets you select a period after which a document will become unverified and set the appropriate person at the company who will be tasked with having a look at the document and confirming that it’s up to date.
But it’s about more than just keeping the documentation fresh.
Maintaining documentation also means keeping a close eye on how the document is used by collecting continuous feedback from users and acting on it.
That’s why quality documentation pages usually provide a quick survey for users, like the one in the screenshot below.
That way, if you notice that a document is being marked as unhelpful, you can take a closer look at it and fix what’s causing users trouble and provide a better experience for them.
Updating API documentation, as well as periodically verifying it and acting on user feedback are all very effective ways of maintaining API documentation.
Make these activities a part of your routine for all existing documentation and you’ll never have to worry if your documents are hitting the mark.
Conclusion
Creating API documentation is no walk in the park. In fact, API documentation is some of the most complex writing you’ll ever have to do as a technical writer.
Luckily, there’s a systematic approach to the process that makes the task much easier and more accurate.
In this article, we’ve broken down the API documentation writing process into seven manageable steps you can take to create efficient, accurate, and extremely valuable API documents every time.
Follow these steps to writing API documentation, and you’ll never feel lost or confused when writing API documentation again.
