Building Your API Documentation Strategy For SUCCESS

So far, we have put together a foundation for our API documentation:

1. We must first move beyond API reference documentation and look for other ways to communicate the value and purpose of your APIs

2. APIs are conversations between client and server. Extending these conversations is important and documentation can help surface opportunities and gaps in the conversation

3. As we write our API documentation, we need to ensure that it addresses the 10 questions developers and decision makers will ask before, during, and after API adoption

With this foundation, our next step is to define an overall API documentation strategy. This strategy will unify your API design and documentation, causing them to work together to produce a better developer experience. At the same time, it will address any questions key decision makers may have along the way.

An approach to API Documentation Strategy SUCCESS

To make it easier to remember, I have defined a simple acrostic as a simple way to help define a complete strategy: SUCCESS.

(S)olution-focused

Your API documentation strategy must first be solution-focused. If your API and related documentation does not help developers and users solve problems, then you will struggle to gain adoption.

A solution-focused strategy means consistently finding ways to:

Explain the benefits that your API provides. For example: saving time, reducing expenses, increasing revenue, and/or improving collaboration. To find your API’s benefits, ask how the lives of your developers and their customers/end users have improved as a result of your API. Your documentation’s role is to keep these benefits in mind and always challenge the API design when it doesn’t meet or exceed these expectations.

Once the benefits are clear, the documentation must guide developers on how to perform the various activities to be done to achieve these benefits. This is sometimes referred to as the jobs-to-be-done, which focuses on seeking to produce an outcome rather than focusing on the product itself. Once we understand the outcome, then we can support the necessary activities to get there.

(U)nified Understanding

There is nothing more frustrating then encountering an API that at first appears to solve a problem, only to realize that their product isn’t a fit because their definition of the problem or assumed domain concepts don’t match to your specific needs.

As technical writers, we must strive to be clear about the concepts our API supports (and doesn’t support). I encourage teams to define their domain concepts up-front. Otherwise, one person’s concept of a ‘project’ is another person’s concept of a ‘team’ or a ‘task’. Be clear, define everything up-front, and reference it consistently throughout your documentation.

On a side note, most web APIs expose resources that are named based on either the underlying domain model or database structures. When you surface these names without first defining your API’s conceptual model, confusion will likely occur. This may be the result of misunderstanding by developers, or something as simple as marketing terms creeping into the names of your resources, confusing developers on the meaning of resources. Be clear, define your concepts, and address areas that your API isn’t intended to solve.

(C)omprehensive

We covered this in a previous post, so I’ll simply summarize it here:

Provide an overview of the API, addressing concerns such as benefits, concepts, capabilities, and pricing of your API to qualify prospects. Also, make your API discoverable so that it can be found outside your website.

Case studies highlight applications that have been built using your API. Provide examples and reference applications to demonstrate some of your API’s capabilities.

Provide a reference documentation for each API endpoint to developers, including details on the URL, HTTP verb(s) supported, response codes, and data formats. Developers use this documentation when starting to consume API endpoints.

Guides offer help with learning an API, including its concepts and vocabulary during this critical stage. They also provide step-by-step guides for implementing common use cases.

Help pages and FAQs can guide new and experienced developers toward a better understanding of your API and proper usage patterns.

Create internal documentation to help your support team when developers get stuck. These assets may eventually become public documentation over time.

(C)ollaborative

APIs are, by their very nature, collaborative. Developers inside and outside of your organization are using something you have built and shared. This means that it is important to find ways to allow your documentation to include community ownership.

One way to accomplish this is by hosting your documentation on Github or other sites that allow for community improvement. We also suggest monitoring for posts and stories that document how someone used your API or struggled with your API, as these will provide greater insights into usage patterns and problems.

Finally, something that is often missed is promoting the products that are using your API. Share what others are doing with your API on your website by capturing case studies (with their permission, of course). This helps them to gain recognition for innovating on your API and helps website visitors know that your customers are experiencing successes with your API.

(E)ngaging

Many of us are familiar with API reference documentation tools, such as Swagger, that offer interactive documentation. This nice-to-have feature is quickly becoming a required feature in documentation today. Beyond this, however, lies a whole other opportunity for expanding your documentation to engage all types of audiences:

• Demos for interacting with your API to perform a task or see it in action
• Videos for demonstrating API capabilities and value to non-technical decision makers
• Tools such as Postman that allow for collections of API requests with sample payloads to be exported and shared with developers to accelerate learning
• Drip email campaigns, driven by the developer onboarding lifecycle and metrics, to teach developers how to use the API for better results or help them overcome problems

(S)trategic

While API documentation should be focused toward external problems, it can also help drive your internal strategy. This includes marketing and sales, which will better resonate if it aligns with your API concepts and solutions. API documentation can also drive search engine optimization (SEO) for organic growth.

API documentation may also drive key performance metrics, specifically customer acquisition costs (CAC) and customer lifetime value (LTV). A well-executed documentation strategy will decrease the customer acquisition costs (CAC), as it will require less sales and support staff to close and onboard the customer. It will also increase customer lifetime value (LTV), as you will be able to increase retention and reduce customer churn.

Don’t overlook your API documentation strategy when defining and tracking your API metrics. It can have a positive impact on your overall product strategy.

(S)ustainable

The final part of your API documentation strategy is sustainability. It is important to select the right tools that the team will use to keep the documentation fresh and up-to-date with the latest API changes.

Tool selection should match the technical skills available on the team. For example, if you have team members aren’t comfortable with Github, then you may have to invest time training them or select something else that is a better fit, such as WordPress. Whatever you select, it should have minimal friction to encourage updates from team members.

Sustainable documentation is important as code deliverables – perhaps more so, as without current documentation, no one will know how to best use your API.