Tips on how to write and maintain simple, intuitive, and accessible documentation.
Software development has always been fueled by developing in a collaborative environment. Frequently, coders overlook the documentation that powers users’ understanding of their code. Documentation helps connect your users to your API and engages your developer community further so that they can make more interesting things from your code. Otherwise, you are left with a book of unreadable code that your users do not want to work from.
Documentation helps reveal the meaning of your code, and how it can be applied to achieve a task. In addition, documentation helps developers get started with your developer experience, allowing them to gain a firmer insight into your product and how your tool can work in collaboration with their code.
In this article, I will outline a few key tips you should remember when writing your API documentation, but by no means is a comprehensive list. Remember to work with your users to develop your documentation, because after all, they are the people who will be reading it.
Maintain a Clear Structure
The glue that holds your documentation together is the structure, and it normally evolves as you develop new features. You should aim for a simple and smooth structure, that makes it easy for beginners to get started with your API, and contributors to maintain a uniform organization in your documentation.
API documentation should contain a thoughtful introduction, that allows users to gain a quick insight into what your API is all about. Remember that your users have not spent hundreds of hours developing your API and documentation, so you need to make it as easy as possible for them to get started.
During development, spend time making your documentation as clear as possible, and provide access to the fundamentals at the very beginning (authentication, header types etc), which will reduce the number of support requests you receive from users about getting started with your API.
Another key aspect of documentation is to make it easy for developers to get started with your documentation as soon as possible. Your API will contain a variety of features, including a variety of endpoints and SDKs, but there is no point in a user reading about them until they know how to get started with your API. Provide them with a clear starting point so that they can work their way from basic features, to the advanced resources in your API.
Write Detailed Examples
Most APIs tend to include many complex API endpoints. It is crucial that you provide additional documentation and support to users so they can easily understand what a specific function does, otherwise, users will send support requests to your team.
If a developer has just started with your API, having examples to work from can be a great way for them to gain additional context into the power of your API. In fact, a large number of developers will look for code they can copy and paste, then tweak to meet their requirements.
Starting with an example allows you to convey the most critical parts of an endpoint, and means that developers have an easy point of reference from which they can build more powerful code from. The best examples generally feature storytelling that shows your users the potential of your API, and how it interacts with other parts of your developer experience.
A great exemplar API to look at would be the Stripe API. Their docs feature examples for every endpoint and also includes easy-to-use examples for every function in their SDKs, so users can start accepting payments within the first few minutes of reading their documentation.
Consistency and Accessibility
Like writing code, it is important to maintain consistency across your entire documentation base. When writing your accompanying docs, it can be easy to forget about consistency, especially considering how long it takes to document larger APIs. Your documentation should be completely uniform and contain no contradictions in code. In addition, check for any parts of your documentation that are ambiguous which may cause a user to become confused, and make sure you add some additional clarification so the user can better understand your article.
You should keep in mind that it should be easy for developers to navigate around. When possible, avoid excessive nesting where you categorize everything into small subgroups which make things very difficult to access. By using a flat structure in your documentation, you can have both a well-categorized and easy-to-navigate portal, thus contributing to the accessibility of your documentation.
You should also make sure that you have linked the documentation throughout your developer resources, and try to make your documentation available offline for developers who are on the go. These little things are often forgotten about by developers, but when they are not available, it can be the first thing they notice.
Think About Your Documentation During Development
When you are writing code, consider how it will look when it has been documented. Many problems in your documentation can stem from the fact that the API itself has not been written adequately. Make sure that you spend time to plan any changes to your API, and reflect on how it is going to look when documented.
If you are working in a team, take some time to have a meeting with not only the developers, but any technical writers involved, and discuss your docs and any amendments that need to be made. If something seems overly confusing to a team member, change it, which saves a user from having to undergo that same frustration.
Some of the things to look out for include: variable names, unnecessary variables, obsolete parameters in endpoints, and so on, which can make it even harder for people to understand your documentation. It is also common for a description of an endpoint or parameter to be vague, as often times developers forget to replace temporary descriptions with intuitive and in-depth ones.
Your team’s documentation will evolve with participation from all users, and as you continue to launch features, your customers should help you better understand how you can improve your documentation. By the time you publicly launch a feature, your documentation should be efficient, and refined, based on feedback from your whole community.
Conclusion
API documentation is what connects your developer experience with your customers. Writing great documentation takes time, and will most likely involve a lot of iteration and revision as your API grows and developers. However, this guide should serve as a starting point on how to write great docs, so you can provide an intuitive experience to all of your developers.
There is also a plethora of resources available online on which you can base your API documentation. Stripe and Google both have some of the best examples of technical writing available. There are also resources like Writing The Docs which provides some more comprehensive advice on writing great documentation.
If you enjoyed this article, consider following me on Twitter @jamesg_oca or checking out some of my other articles on Hacker Noon.