Making documentation successful
Making documentation successful
How to design your documentation to be actually used effectively, and how to help developers get the most out of your API documentation
We often hear from our customers that API integrating partners never read their documentation. They prefer to hop onto a call and resolve queries rather than mine a dozen pages to solve their issue. They’re impatient. They’re not sure where, or even IF they’ll find what they’re looking for, in the documentation.
This can be frustrating - not just to the authors of the documentation who have worked hard to designed the information architecture and detailed the content, but also to teams handling support, partnerships, etc. due to all the escalations and back and forth.
Learning from how developers actually use the docs, we can design the best-in-class docs portal - including the optimal way to organize documents on the portal, and how content is laid out in each page to best fit with the usage.
Know your audience: Who are the API docs written for?
When it comes to API documentation, it is important to recall who we are writing it for (“who is the audience”), and what they are likely to use it for.
The audience is likely to fall into these 2 broad categories:
Business and product folks, who want to understand whether to use these APIs and how they are to be used. They’ll likely want to have a conceptual understanding of the offerings, common use cases and process workflows.
Developers, who will use the API to integrate with, for their tasks at hand. They’ll want to get started immediately, and need assistance to write code and debug issues.
How are API docs used?
Business and Product Folks
Skim the ‘Table of Contents’ and ‘Section Overviews’
Business and product folks are typically “top-down” - this group will orient themselves to the documentation by looking through the table of contents, and for sections that are relevant to them, they will double down, but first look for an overview of the section.
Engage more on visual or interactive content
This group has a low attention span, and tends to skim over long-form content, but pauses on visuals (images, infographics, diagrams), and prefers video or interactive content.
View on a variety of devices, including phones or tablets, at times, on the move
This group of often busy. They access content at times while they’re traveling, from a device that isn’t always a laptop screen.
Developers
“I don’t read all documentation - that would be really boring. I read what absolutely I need to, to get the work done, plus some false leads, and some interesting stuff for its own sake.”
- Our (lazy) software developer
Skim the ‘Table of Contents’ and ‘Section Overviews’
Developers are typically searching for specific topics, and their objective in looking through the table of contents is primarily to locate the topic covering their issue.
Use Ctrl+F
Developers extensively use the “Find” function - to search for specific topics within blocks of text, search through references for a particular field, etc.
Code alongside
Oftentimes, developers are coding alongside, and visiting / revisiting documentation for either guidance (i.e. following a how-to guide step by step), or resolving a specific issue (for example, looking through code samples or references) and directly translating their learning from the documentation into their working code.
How can we help developers to get the most from the docs?
Everything in one place: build a one-stop portal with all documentation categories - don’t have your readers shuttle across multiple sources (multiple websites, email exchanges, downloadable files, etc.) to search for information.
Simple, intuitive menu items in the Tables of Contents: ensure that the language and naming in the Tables of Contents, menu items, and overview sections is simple, crisp, and intuitive - your audience is likely to use this as a starting point, and it is important that you don’t lose them at the start!
Have an overview for each section: an overview helps the reader know whether the information in the section is relevant to them, and saves them a lot of time searching or reading through content.
Searchable: most readers will want to first search the documentation to ensure that it contains what they are looking for, and read the section that their query lands them in. Make sure that there is a global search function, and make sure that individual pages are laid out flat and searchable. Avoid embedded documentation, collapsed sections and web elements that make it harder to search
Visual: visual content, including infographics, diagrams, or even video content is gaining prominence and increasingly in demand. It is oftentimes more effective to explain concepts or guide the development process via videos - these are easier to follow than long-form content, especially since videos have the dual advantage of a voice-over explanation along with demo screens / code samples.