When defining an overall API documentation strategy, it means that this strategy should unify your API design and documentation, causing them to work together to produce a better developer experience.

The most important thing to remember that most of the users / readers of your restful API are developers or at least have some sort of technical knowledge, so the restful API documentation strategy should be more technically oriented.

A few weeks ago I was reading a very interesting blog post by James Higginbotham called Building Your API Documentation Strategy For SUCCESS, I have decided to summarise his SUCCESS Strategy in our blog as well:

(S)oftware \ Solution-focused

Your API documentation strategy must first be software or solution-focused. This basically means that your documentation should reflect your solution.
If your API and related documentation does not help developers and users solve problems, then you will struggle to gain adoption.

Once the benefits are clear, the documentation must guide developers on how to perform the various activities to be done to achieve these benefits.

A solution-focused strategy means consistently finding ways to:
Explain and emphasize the benefits that your API provides.

For example: saving time, reducing expenses, increasing revenue, and/or improving collaboration. Your documentation role is to keep these benefits in mind and always challenge the API design when it doesn’t meet or exceed these expectations.

(U)nified Understanding

Be clear, define your concepts, try to address everything up-front, reference strong points consistently throughout your documentation and address areas that your API isn’t intended to solve.

Technical writers must strive to be clear about the concepts our API supports (and doesn’t support). Teams should 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’.

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.

(C)omprehensive

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.

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.

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.

Restful API 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

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.

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.

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.

(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

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.

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.

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