How Documentation Affects API Quality
If quality depends on consumers' perception, how can API documentation influence it?
Quality is almost impossible to measure and communicate. While for some people an API can have the best quality, there are others who see it as something that can be improved. In a way, what you're looking for is a measure of how consumers value their interactions with the API. And, one of the first things consumers interact with is API documentation. Can it be a major factor in influencing the perception of quality? Let's find out.
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.
To Peter Drucker "quality in a product or service is not what the supplier puts in. It is what the customer gets out." Drucker's view of quality is customer-centric. To the author, the ultimate judge of quality is the consumer. Only consumers can, without argument, tell if a product has the desired quality. Philip Crosby, another quality management expert, goes further and believes that friction is in direct opposition to quality. To Crosby, a lack of quality translates into "all the actions that involve not doing jobs right the first time." And, it's this notion that makes me think that documentation has a major influence on the quality of an API.
I wrote before that helping consumers "find their way into your API is crucial, otherwise, you'll lose them right when they're just getting started." It's this first step that dictates the perception new consumers have of an API. Even before they start using it for the first time. If you think about it, the investment new consumers make when they decide to use an API needs to have a return. And the return needs to happen in a relatively short time. Otherwise, those new consumers will simply walk away unhappy with the experience they found.
You can help new consumers find their way through an API by providing all the information they need at the right time. Think about your documentation as a product and find the personas you want to write for. Because not all consumers have the same needs, offering a customized "getting started" how-to is one way to provide a quick entry into an API. You can customize the entry path by identifying possible interests customers have. Create a how-to guide that starts with the goal of succeeding in each of the API features. Consumers will feel attracted to the features they're looking to use and will immediately follow the steps you provide on the corresponding how-to.
Another way is to conduct customer research. Your goal is to understand the jobs to be done (JTBD) for each identified persona. Then, create a tutorial for each JTBD where you show how consumers can use the API to fulfill their use cases. It's natural that the solution to some JTBD will involve some API features and perhaps some other existing product. Take the time to document those relationships and explain how the API can work together with other solutions. The objective is to write from the consumers' perspective and show how the API can fit into their world. It's not the consumers who have to adapt to use the API. Instead, it's your job to show them how the API can adapt to their world.
However, offering too much documentation can also decrease the perception of quality. Even the best documentation can be a source of friction. Fortunately, there are ways to understand when there's friction and counteract it. One such way is by measuring how long it takes consumers to start using the API. This metric is called Time to First Call (TTFC) and is something you can use as way to measure the perceived quality of the API. A low TTFC means that consumers take a short time to start using the API. Indirectly, that means the onboarding experience—and the initial documentation—is good. And that, in turn, translates into a higher perception of quality.
What about those situations when consumers can't really find out how they can start using the API? One way to recover those failed attempts is by proactively contacting those consumers and helping them manually. This is what I call proactive support and is something you can put to work by analyzing consumers where the TTFC is above a certain threshold—or inexistent. By getting in touch with consumers who invested their time in trying to use the API you're showing you care about them. If you succeed in helping them use the API their perception of quality will increase. And, in the end, you can translate each specific support request into a new use case tutorial. Hopefully, in the future, new consumers will find it and will be able to use the API by themselves.
It looks like documentation is the most important factor in influencing the quality of an API. It's the first thing consumers interact with. It's also the storefront of the API and what everyone will see. If the quality of the documentation is not good enough, there's a high chance the API itself doesn't have enough quality. Investing in writing clear and objective documentation aligned with what consumers want is a priority for anyone serious about building API products.