The API ecosystem is expanding swiftly. Organizations are more dependent than ever on interconnected web services and integrations, and providers have the chance to drastically increase the usage of their APIs.
Developers prefer working with APIs that are simple to understand and function as intended. High-quality documentation can inform users, set expectations, and encourage developers to use your service for new projects.
Here are some ideas for how your group can create world-class documentation:
-
Tell a Big Story
What greetings do people see when they first visit your API documentation website?
You should tell a story if you want to increase adoption and create a foundation of loyal users. Although documentation sometimes gets a bad image for being overly technical and extensive, for many businesses, the documentation now serves as both the product’s packaging and user guide.
What is your narrative, and how do users of your API fit within it? Marvel, for instance, has a public API that enables developers to search the canon of comic books.
The message is unmistakable when someone enters the portal: “Create Awesome Stuff with the World’s Greatest Comic API.”
Even if your company’s APIs don’t rely on superpowers, there’s undoubtedly a tale out there that highlights your advantages and inspires developers to use your API.
-
Provide a Clear Starting Point
Okay, you’ve persuaded your new users with a gripping tale. What’s next?
Give developers a clear place to start so they know where to look to learn more about your API. The well-known messaging platform Slack does a decent job doing this in its API docs. The dynamic heading “Build: brilliant bots” tells a story while the “Start here” section introduces the side-panel navigation.
Before they even scroll down, visitors have a prominent area to begin learning about the API, giving Slack a dedicated location to establish expectations with new members. The “Start here” part follows the typical software development lifecycle, which includes the steps of planning, designing, and building. Think about the best organizational structure for your API, but make sure you point new users in the right place
-
Establish a Structure to Support Common Use Cases
By the time a developer reaches your documentation, unless they are just browsing, they typically already have a project in mind. You may shorten the time it takes for developers to obtain the information they require by highlighting the most frequent use cases or operations your API can enable. The homepage of Slack does a wonderful job of highlighting operations like “Build bots,” “Send messages,” and “Create straightforward processes.”
Spend some time thinking about the kinds of things your end users are attempting to produce and how you can give them the most beneficial information upfront. Making their initial project with your API simple will increase the likelihood that they’ll return frequently.
-
Write for Humans First
Beyond your documentation, some developers might never engage with your company. Developers may find what they need in clinical, dry documentation, but the experience won’t stand out. Consider your documentation’s tone. Is it a casual conversation?
How would you describe the available authentication options to the developer if they were seated next to you?
You must project trustworthiness, therefore avoid using slang excessively and avoid being dry and cryptic. You might wish to start by using a readability calculator to assess the readability of your current documentation.
These calculators will hold you accountable and point out any passages that may contain excessively long words or run-on sentences. Reading ought to be simple; coding is difficult enough.
-
Make it Comprehensive
Developers have high expectations for an API provider’s documentation. We asked respondents to list the “top 5 most important items you look for in API documentation” in our 2019 State of API report. Here are the findings from more than 3,000 software specialists:
Make sure all of the resources you offer to customers are comprehensive. Don’t let a lack of documentation discourage your most enthusiastic user from accessing your documentation.
This does not imply that you should overwhelm them with data. Use hierarchy in your documentation so that power users may navigate through the information at their leisure and light users can
-
Make it Interactive
Respondents chose “Examples” as the most crucial element of API documentation in the graph above. Developers want to use your API as soon as they can to explore what possibilities exist.
Interactive documentation allows programmers to easily test out various API calls. This option exists on the Marvel site that we already mentioned. An API key is immediately given to you when you register an account. With that key, you can call all the various endpoints and experiment with various procedures. The parameters and error messages developers should anticipate seeing are also made more familiar to them by this interactive page.
-
Standardize Your API Design with the Open API Specification
The industry-standard API description format for REST APIs is the Open API Specification, formerly known as the Swagger Specification. Nearly 70% of respondents to our 2019 State of API survey are now using the Swagger/OpenAPI standards to define their APIs, according to our findings.
Both humans and machines can easily learn and understand this format.
Your company can give developers a consistent experience by consistently structuring your APIs. They’ll be aware of what to anticipate and where to look.
Adopting the Open API protocol enables organizations to use free and open-source technologies like SwaggerUI to transform their API specifications into interactive documentation.
All of the additional open-source Swagger technologies, including SwaggerUI, are accessible through a single platform called SwaggerHub. You can register for a free account and begin adding your APIs right immediately if your
-
Highlight Tutorials, FAQs, and Case Studies
Your API can be learned from your documentation.
You can describe how to use your API, but nothing will make it come to life like actually using it. For straightforward project types, provide tutorials and include links to them in your documentation. The Slack example below demonstrates the kinds of articles and tutorials they are creating and promoting to assist users in becoming knowledgeable about their API.
A few case studies are also listed. You should inspire visitors to create new projects in addition to educating them about your API to encourage usage of it.
Kip, a penguin-themed bot that assists in coordinating food orders for offices, is one innovative example that Slack offers. By showcasing some of your most inventive users, you can make it simple for developers to understand what is.
-
Encourage Feedback from Users
How well does your documentation work?
Although your team could make a lot of assumptions using only those indicators, you could use other metrics as proxies, such as page views, consumers, or calls.
You could conduct user surveys to learn what people think, but if user feedback isn’t ingrained in your infrastructure or process, it can be difficult to maintain discipline while asking for it. The most effective documentation welcomes user comments within the documentation.
The well-known payment provider Stripe excels at this by posing the question “Was this section helpful?” after each section in their documentation. Users can quickly click “Yes” or “No” while the process is still in progress.
They can easily determine which portions are the most marked as being unhelpful and which areas have the most engaged visitors by asking this question, and they can subsequently prioritize adjustments under those findings.
Although this component gives you a quantitative evaluation of your current paperwork, you will not be aware of any potential gaps. You can get a reasonably decent idea of the state of your documentation by combining embedded quantitative indicators with qualitative questionnaires.
-
Keep it Up to Date
Reading paperwork that just serves to further complicate matters is annoying.
If your API documentation is out-of-date, it may reflect poorly on your company and deter developers from using it.
Your team must rely on tools that can speed up your workflow and free up time to address these difficulties. We already mentioned how the SwaggerHub platform and technologies like SwaggerUI can produce documentation for your API definitions automatically.
In addition, search for dependencies that hinder your team’s performance. Does your documentation team have to wait for the completion of development work before beginning?
Waiting for work from other teams results in avoidable time constraints, which lowers the caliber of your documentation.
Tools like Service V-Pro and VirtServer make it simple to turn your API design into a virtual service that can be shared around teams if your team is utilizing the Open API definition.
Using the virtual service, your teams for documentation, development, and testing can all operate concurrently. You can start accurately documenting expected responses without waiting on other teams if there is one shared source of truth for the project.
If your team uses SwaggerHub, it’s easy to integrate ServiceV into your workflow so that virtualization is a natural part of your workflow.
