API Documentation Consumes Attention
API Documentation Consumes Attention
Developers consume API Documentation and, in turn, it consumes their attention.
Good documentation can also be a source of API friction. If it's too simple—or even non-existent—consumers won't know how your API works. If it's too comprehensible developers will find it hard to follow. In the end, your role is to shape your documentation to what consumers really need.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
How long does a developer take to make a first request to your API? TTFC, or Time to First Call, is a metric that measures the amount of time between reading an API documentation and making a first request. You can consider an API with a low TTFC as high quality. This metric is so important that it's often used as a way to determine if the documentation—and any other step required to use the API—needs improvement.
So, TTFC is quite important and it depends on the API documentation. That means the documentation is in the critical path to a successful API onboarding and subsequent retention. Any friction you introduce to the documentation translates into a higher TTFC which, in turn, will create a lower developer activation and retention. In other words, the success of your API depends on how useful the documentation is to newcomers.
But, how thorough should your documentation be to be useful without imposing too much cognitive load on developers? Your goal is to convert a potential consumer visiting your documentation into an active developer using your API. Focusing on the onboarding experience means you need to understand the use cases of your consumers.
A good example of an API with straightforward onboarding is OpenCage. Even though they provide extensive API documentation the onboarding instructions are to the point and easy to understand and follow. In fact, onboarding is so easy they end up having to support API consumers who don't have enough knowledge to build their integrations. Ed Freygole, OpenCage's co-founder recently shared with me that some universities use the API in introductory Computer Science assignments. Students sign up easily but later on they need support to keep using the API on their own.
In this case, the API documentation introduces almost no friction to developers. The friction then comes from the lack of knowledge some consumers have. However, this example isn't the API documentation you typically find. In most cases, developers need to spend more time understanding what the API does, how to sign up, and how to make a first call. The habitual API documentation requires a high level of attention from potential consumers.
Finding the right balance between being too simple and too sophisticated isn't easy. You might get away with a generic onboarding how-to guide if your API focuses on one single feature (as OpenCage does). Otherwise, you need to craft different onboarding experiences for each one of the consumer use cases you want to support.
One thing that works for me is learning as much as I can from consumers before writing any API documentation. Then, I focus on the top use cases potential consumers are interested in. Since those will be the top entry points for most new API users, I prepare a tutorial for each. Each tutorial offers a safe environment where developers can easily sign up to use the API. Then, by following the steps in the tutorial they will end up implementing the integration that fulfills their use case.
What about all the other use cases that you can't cover with your list of tutorials? It's not easy to find and write a tutorial for each specific use case. There are two complementary approaches that can help you grow your "tutorial catalog" over time. One approach is proactive and requires a periodic analysis of what developers are interested in when they browse your documentation. You can, for instance, analyze the keywords people used on search engines that led them to the documentation. Or, you can analyze the browsing behavior of users to find patterns. Your goal here is to understand what users find interesting and write a tutorial if one doesn't already exist.
The second approach is reactive and relies on direct feedback from users. You can obtain feedback directly on your documentation pages and also through any interactions with your support team. By analyzing the questions users ask you can infer the use case they're trying to fulfill. Then, you use those questions and the answers you provide to write a new tutorial. You can then point users who ask similar questions to the new tutorial and improve it over time.
But even these two approaches require manual labor and might take a long time to produce results. There's another solution that's gaining adoption lately. You can offer a user interface backed by AI that answers any question related to your API. Users simply have to ask and the system will provide the best answer. It's not hard to build a system like the one I'm describing. I recently built an experimental system using OpenAI and it took me no more than 30 minutes. I can now ask any question about any API—provided I know its OpenAPI definition document—and obtain relevant answers, including generated code in my favorite programming language.
In the end, your goal is to reduce the amount of attention consumers need to understand and start using your API. Simply making it very easy to sign up is not enough. You have to make it simple to use your API in a way that's meaningful to your audience. After all, that's why consumers will end up using your API.