How to write and design good API documentation
This is a pre-publication of some thoughts I shared with Thomas Bohm, the Director of User Design, Illustration and Typesetting journal for an interview you can get HERE.
What’s an API
An API (application programming interface) allows different pieces of software to communicate with each other. It consists of a series of requests that tell a system what needs to be done, and then return an appropriate response. For instance, you can use the Infobip SMS API to submit a request that will send an SMS from one mobile to another, and all this information (sender’s and recipient’s phone number, message content, and so on) will be included in that one request. So, in a way, an API is a very efficient way of retrieving information from servers and making different programs interact with one other.
API reference is a visual representation of the API. It documents all possible requests and responses that exist within this API which you, as a developer, can use for your own purposes. An API reference tells a developer how to use the API by providing code samples. This will typically be in cURL which is a command-line tool for receiving or sending data using a URL syntax. But since APIs are language agnostic (you can use any programming language to develop software based on an API), you’ll also see samples in many different languages like JavaScript, PHP, Python, and so on.
Very often a good API reference is complemented by tutorials that showcase how to use the API for the most typical scenarios the API is designed for. For instance, an e-commerce API will most likely include tutorials on how to use the API to add a product to a cart and checkout, or how to apply a promotion to a product.
Why Stripe API is widely regarded and talked about as good
The quickest answer as to why Stripe API reference documentation is so highly regarded is that it ticks all the boxes. It caters for a wide range of audience with different degrees of experience. It even asks you right at the top of their API reference page whether you are a developer, and if you are not, it allows you to read about a Stripe account extension that can be used without any programming knowledge. The API itself is very meticulously referenced. All parameters are flagged with the required or optional label, making it so much easier for a developer who’s not familiar with the API to make their first call. There are a lot of code samples in a lot of languages to choose from, including the most recent ones like Go Programming Language, which clearly shows to the user that this reference is well-maintained and updated on a regular basis.
All errors are very nicely documented with a description and possible fixes. This is important for every developer who doesn’t want to spend ages on a support call but would rather like to troubleshoot their issues on their own. The API versioning process is explained and so you can be sure that the endpoints you end up using are going to be valid and compatible, even if the API version changes. This means that you can benefit from all the recent updates to the API itself, without a huge maintenance burden imposed on your own code. From a content point of view, Stripe API reference is very easily navigable, and information is presented in a clean and consistent way.
There’s no clutter, no information overload, but rather easily predictable content structure that enhances the learning experience. All additional information, that is not necessary for the API reference but is useful for those who want to know more about a topic, is included in a separate document that deals with more conceptual aspects of the API. The reference links out to that document quite frequently, so you don’t have to forage for information on your own. Last but not least, if you want to play with the code a little bit to see its full potential, you can head to Stripe’s integration builder where you can do it without the need to set up your own environment. You are even provided with some mock data which you can use to simulate the payment process and see the code needed for that.
How to document an API well?
When it comes to API reference, you need to remember your audience and why the API reference exists in the first place. You’ll have two types of users. You’ll have implementation specialists who’ll want to assess the API and see whether they want to use it for their implementation. 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. Implementation specialists are often busy, and on the move, so thinking in terms of responsiveness is a really good strategy. In other words, make sure you cater for various devices, so that your content is easily accessible from different screen sizes. The other type of user is the obvious one, the developer who’ll use the API to implement it into a project they’re working on. Developers want to get started fast, so make it easy for them to find basic information, like how to authenticate, what the most common errors are, and what the base URL of the server where all the resources live in is. A really good example of how to make sure a developer can start using an API almost immediately is Infobip API reference. You create an account, and then when you login to the API reference, it shows you endpoints that are personalized based on your login credentials. All you need to do is to use cURL examples or any API client, like Postman, to test these endpoints, without the need to set up an elaborate test environment.
Such an approach also ensures that your traffic goes through the most optimal route, increasing communication speed and with it the entire user experience. And this is something that is very easy to overlook when creating API documentation; developers are not only the target audience, but also users who are striving for a seamless user journey. Another good rule of thumb when it comes to API reference content strategy is making sure your code samples are kept up-to-date, work, and are easy to copy and paste, because that’s exactly why they’re there. To me personally, a good API reference would always have a copy button that would copy the entire code sample with just one click, removing the possibility of not grabbing the entire sample when trying to do the same thing manually. It’s a fairly common feature nowadays, but it certainly deserves a call-out.
How much effort and time does it take to develop an API?
The short answer here would be there is never enough resources or enough time to write a perfect API reference. Joking aside, I’d say that it would depend on how complicated the API is, rather than how many developers are working on it. Another question is who’s doing the QA (quality assurance), developers or a dedicated team of testers? Ideally, there would be a separate development team working on the API, and then the API would be released in stages for the testers and writers to test and document it. Then, all teams would engage in a review process to make sure the code samples are syntactically correct, and the content is technically accurate. Typically, you have developers doing everything, from working on APIs to writing documentation. If you are lucky enough to have a writer on the team, the writer would typically go into the file that’s already been written and edit the content to make it more presentable. Companies nowadays are starting to realise that this is not an ideal situation, and technical writers who specialise in documenting APIs are getting noticed. You can see the shift in the job market, as more and more technical writing jobs now requires to be familiar with APIs and ways of documenting them. A research done by Cherryleaf (2003) measured the ideal ratio of technical authors to the number of developers. According to them, the ideal ratio was a ratio of 12 developers per writer for organisations with fewer than 500 developers and where developers do not produce user assistance documentation. As for how much time it takes to develop an API, it all depends on what your plan is. Are you planning to have your prototype deployed and documented as an MVP (minimal viable product) to build upon that with time; or would you rather go for a more sophisticated architecture, taking into consideration all crucial aspects of a good software: reliability, security, data processing speed? In recent years, we have observed a boom in startups. This shows that developers tend to deploy an MVP to build upon. Typically, they would provide an opensource version of the API hosted on a collaboration platform like GitHub, so that other developers that are interested in using it can contribute to its development. Then, as the product matures and is improved upon, they start thinking about some billing plan to capitalise on that API.
Is there a scenario in which API is not a good solution?
There’s a bunch of technology that has originated using different protocols and data exchange processes which is now slowly trying to reach the API world. A good example is the company I worked for, OpenMarket, and the company that has recently acquired it, Infobip. Both companies provide mobile networking software which allows mobile devices to communicate with each other. SMS (short message service) and MMS (multimedia messaging service) have been with us for a long time now, and they haven’t started as REST (Representational State Transfer) APIs. And so, SMS and MMS APIs are still considered quite new technology. Their main advantage is the speed with which they exchange data, but the main drawback is that there’s a limit to how much data you can send reliably; so, if a company wants to send a lot of messages on a regular basis, they may encounter some traffic issues using an API-based solution. A lot of companies still use traditional data exchange protocols, such as SMPP (short message peer-to-peer) for SMS or MM7 for MMS because it’s familiar and reliable, and most importantly, because it uses binary files which are great for storing and exchanging large amounts of data. The disadvantage of such old systems is that they are complex to implement and maintain, so they’re not cheap. APIs are more cost effective as they’re easy to implement, build upon, and maintain.
How to design your content well
First and foremost, you need to remember that people turn to online guides to solve a specific problem they have. They don’t necessarily want to read a description of all UI elements that a particular piece of software has. They want to find a solution as fast as possible. There’s still some variety in the way people will reach that piece of content though. Some will use search, and some will use a table of contents. So, it’s up to a technical author or instructional designer to come up with as many paths to the same piece of valuable content as possible, so that it can be easily reached by everybody. You never know how your reader will arrive at a topic. It may be the very first thing they are reading, so you don’t want to confuse them right at the beginning of their reading journey, even though for you it’s the middle of a larger piece that you wrote. A number of content strategies can be used here. Ted Baker wrote a really good summary of how to approach online content, called Every page is page one, where he explains how vital it is to explain the context for each topic you create. So, you basically treat every topic as a separate standalone article, with all your typical necessary bits like introduction, purpose, audience, body, summary. This approach is based on one of the most popular content strategies called ‘topic-based writing.’ It has several advantages to the user and to the writer. A user will always know where they are, and why they’re reading what they’re reading, because it’s all there in the introduction. The writer has at their disposal a number of self-contained topics that they can reuse in different places, without the fear that they will seem out of context. API documentation is a bit different. Although some parts of it are standalone (endpoints, error codes, and so on), and can be reused and moved around, there’s a certain hierarchy to how you interact with an API. For instance, you cannot use the API unless you authenticate your endpoints, so that would probably be the very first thing you want to read about as a developer. This is why it is important for a technical writer to know how an API is used by developers before they document it; and why it is so important to collaborate closely with the development team to create the best possible user journey while maintaining the contextual integrity any technical author strives for.
How do you know that the API documentation is working well for people? And what measures do you have in place to deal with user feedback and remedy issues and bugs?
End user documentation is very often used by your own colleagues from other departments, like sales, support, customer experience. The easiest way to check for usability is to encourage your colleagues to share their feedback and raise any issues as soon as they encounter them. Documentation issues and bugs like typos, invalid URLs, or missing images need to be dealt with immediately, as these should have been caught during your standard content QA (quality assurance) process prior to publishing. Bigger issues like user feedback should be carefully looked into and prioritised. Sometimes when you try to resolve one issue, others arise. For instance, imagine that a user came up with a more descriptive title for your article, which is great and looks like a quick fix. But now you need to think about all the changes this one little thing can trigger. If you change a title, you’ll also need to change the table of contents that lists it. Is the URL going to change? Is the article linked to from other places that need updating both the title and the URL? Apart from the content itself, and I exclusively speak of online content here, we should also measure how our users arrive at it. Nowadays, it’s quite easy and common to plug into the site where your content lives, a tool that tracks and reports the traffic. You can then tell which sites are the most popular ones, and which ones are not. You can also check what search terms were used to find specific articles, so that you can then adapt your content accordingly. If an important article, which you know users will most definitely benefit from reading, has few views, this means that most probably the article is buried too deeply in your current content and is overlooked. The easiest way to check this is to elevate the content and make it easily findable. If the location of the article is indeed the issue, your page views should now bounce up quite quickly. If not, you’ll need to figure out what other reasons there could be for the low number of views; maybe the language used in the article is too technical or complicated. The easiest way to test this would be to use a tool that analyses readability and suggests content changes based on that factor.
“You have to learn if not to code at least to appreciate code, to understand code. Because code is what nuts and bolts were a hundred years ago” (Spiekermann, 2016). Are programming languages and technologies going to change in the future?
JS: I definitely agree with Spiekermann. Understanding the principles of coding is quite important if you want to understand how a developer looks at the code and works with it. Without that knowledge, you will never be able to fully cater for this particular audience. If you have to document a user interface, you look at how it works and put yourself in the shoes of a typical user. Similarly, if you need to document code, you will have to at least understand how it’s going to be used by other developers, and what would be their typical pain points that you could solve with your documentation. I wouldn’t go as far as learning how to use a framework, frameworks come and go (Allen, 2018). Back in 2013, the hottest and most fashionable framework was Ember (2021). Nowadays, hardly anybody works with Ember, because other frameworks have gained in popularity and have a bigger developer community to help with troubleshooting. So, instead of learning about something temporary, it would be more beneficial to familiarise yourself with some basic computer science concepts, or to do a beginner’s front-end developer course, to learn about the concepts anchored in this particular context.
Accessibility in online output
We live in the golden era of a customer-centric design. It has a lot to do with accessibility and inclusiveness, but I fear we are still not doing enough. From what I’ve observed over the years, any MVP (minimal viable product) will focus on accessibility only as a nice-have not a must-have. It’s not a blocker, if your website uses an old front-end library like Bootstrap (Bootstrap, 2021) v4 or even v3, which is not very friendly when navigating with a keyboard or using a screen reader. Version 5, which was only released in May 2021, so it’s still fresh news, is more focused on accessibility and it is much more robust in terms of the CSS styles you can apply for screen readers. Fortunately, as well as releasing their more friendly version, Bootstrap recognises where they’re falling short and is working hard on improving accessibility, which is very commendable of them.
How APIs might evolve in the future
More and more companies include an API in their technology stack (combination of programming languages, frameworks, and tools that developers use to build a web or mobile app). More and more, successful start-ups compete against big industries, with their state-of-the-art, fast APIs and amazing documentation. So, I think there’s a huge shift in the API industry’s mindset. Documentation is no longer considered just a reference of endpoints a developer can implement in their project. It is an advertisement for a technology that should be appealing to both developers and business decision makers alike. It’s about a seamless and eye-catching user journey, as well as informative documentation and easy-to-implement features.
