Every day, application programming interfaces (APIs) are created to speed up the development of modern software applications—from globally-scaled public services to internal endpoints for your proprietary applications.
For engineering leaders with teams that write and maintain APIs, however, it can be difficult to know how to prioritize API features, encourage adoption, and respond to feedback from developers. And as we at VMware Pivotal Labs well know, rapid iteration leads to product success.
In this post, we’ll cover how great documentation allows you to respond quickly to change, prevent developer fatigue, and develop APIs that satisfy your most important business needs.
Focusing on how an API’s documentation can
-
Increase the adoption of new and existing API products
-
Improve developer satisfaction and productivity
-
Decrease the lead time from API feature request to working, documented software
Why we write documentation
API product teams often think of documentation as a means to an end. The users of your APIs (whom we will call “consumers” from now on) need to know what endpoints or methods your interface provides, and documentation is a straightforward way to provide that information.
From “hints” that pop up in an editor (like VS Code’s Intellisense or NetBeans’ Code Assistance) to websites with code samples and tutorials (like Stripe’s integration docs), these written API descriptions provide quick references that enable consumers to solve their product-specific problems.
But documentation can be so much more than just reference material. Since many APIs are typically not visible on the screen, their documentation becomes the method with which your consumers, product owners, and executives evaluate the quality of your product. In a sense, your docs are the “front door” to your API product.
Let’s take a real-world example: When a visitor arrives at someone’s home, the host who greets them at the door will welcome them and direct them to comply with any house rules, saying for example, “Please take your shoes off in the entryway.” They will also make the visitor aware of where commonly used areas are located, such as how the bathroom is down the hall and to the right.
Good documentation also greets consumers with a friendly face. Great documentation, however, presents the purpose of the API up front and explains its rules, for example, “To authenticate, send an auth token with the following format…”
Good documentation makes common use cases easy to find and provides multiple examples to make integration simple. Great documentation, however, makes clear to consumers the layout and architecture involved.
Most documentation
-
Explains how to access and/or authenticate with an API
-
Documents endpoints and interfaces that consumers can integrate with
Well-designed documentation
-
Introduces API consumers to domain-specific knowledge necessary for integration
-
Accounts for edge cases and gives consumers a way to request new features
Providing these features alone will increase the adoption of your product teams’ APIs.
At VMware Pivotal Labs, we are often brought in to modernize APIs. Some have sparse documentation, while others might require deep domain knowledge to even begin integration. By writing up (or even automating) common use cases and treating API documentation like a product, we’ve seen:
-
A decrease in the number of questions about common problems (like authentication or getting access for the first time)
-
An increase in the number of consumers that have successfully integrated
-
An increase in developer satisfaction due to having to spend less time spent integrating
How can [our API] help users meet their product’s goals?
Once documentation is written and available to consumers, API product teams can focus on building a product that meets those consumers’ needs instead of just answering common questions or debugging edge cases.
One way to understand consumers’ goals is to survey developers who are integrating with your API. Or better yet, watch them as they do! Common user research practices like usability studies, in-depth interviews, and quantitative surveys can highlight key problem areas with onboarding.
Adding an analytics solution can further improve the business’ understanding of API usage by monitoring endpoint usage or identifying common documentation pages and use cases. AppDynamics Application Analytics can easily be added to applications hosted with VMware Tanzu and can be leveraged to understand doc site usage.
Getting close to the problems that their consumers face on a daily basis lets API product teams deliver solutions that directly impact the business by allowing the needs of those consumers to determine the priority and impact of new API features.
Beware of bias
Although it may be tempting to suggest that teams “dogfood” their API by creating a sample integration and using that as a proxy for user feedback, this method alone rarely captures the needs of an API’s actual consumers.
A great example of this can be found in the history of the React UI framework. During a conversation with React Podcast, Pete Hunt, an early developer on Facebook’s React team, reflected on how the he and his colleagues responded to criticism that the way their new library expected developers to write user interfaces (UIs):
We got really good at answering people’s questions and understanding [our users’] concerns. We realized that there was this whole lineage of how Facebook thought about UIs that was pretty diverged from how the rest of the world built them…and we started writing the documentation to address that.
This rewrite of the documentation, along with a talk that Hunt gave at JSConf EU that same year, provided a path for developers to update their mental models and rethink “best practices” for front-end development.
Today, React is the #1 front-end JavaScript framework by far. This is the type of transformation that a user-centered approach to API design and documentation can deliver.
Getting started
If your team hasn’t done so already, get a quick description of the API product written up and put it where people can find it. Whether it’s an internal wiki, a collection of GitHub pages, or a channel description in the team’s chat client, a simple and clear explanation is the first step to getting closer to your API team’s consumers.
Then augment this explanation with more detailed documentation. VMware Pivotal Labs teams have had success using tools like ReDoc, Spring REST Docs, and, for front-end APIs, Storybook.
Whether a team is auto-generating docs or writing them all by hand, its members need to keep top of mind the way developers naturally read documentation. The same principles that apply to any technical writing apply to documentation as well:
Minimize and simplify words — Whenever possible, use simplified, technical English (think 4th to 7th grade reading level). Also, define any new or unfamiliar terms, and be sure to use them consistently.
Make sure information is mapped to the correct formatting — Use headers to separate distinct sections and break down steps into lists or bullets.
For a deeper dive into good technical writing, check out Google’s “Technical Writing One.”
API documentation should be updated as often as the codebase. Even if a team has a dedicated technical writer, team members should still write a first draft. The closer the author is to the product, the better the docs will be.
As API and documentation updates are made, teams can leverage analytics and user research to keep track of what consumers really need. Feedback, along with the ever-changing needs of the business, will inform future iterations.
For more on how to integrate documentation and a balanced team into API design, including examples of interview scripts and REST API best practices, check out Principles of Designing & Developing an API Product.
Want to speak with someone about cloud native development? Sign up for Pivotal Labs Office Hours with an engineer, designer or product manager to talk through a technical challenge or business idea.
