The future of APIs is about user experience

And how documentation can make a decisive contribution in the user experience

One trend to watch for in the future of APIs is a more intense focus on the customer experience.

A customer-first approach is the antidote for a majority of the issues (present and maybe also future) that API developers and users struggle with. The realities of business and software development tend to nudge outcomes in exactly the opposite direction, and where APIs are concerned, the documentation often makes the difference between a disappointing experience and a better one.

Here are the documentation factors that have an impact on usability.

Completeness

Documentation should include everything that users need to successfully adopt the API and continue to use it:

• Reference docs that cover every single parameter of every single endpoint, as well as topics like auth, error codes, and rate limiting.

• A get-started tutorial.

• Conceptual material that explains what the API is, the problem it solves, how it works, and what it can and can't do.

(I've written more about that starter set of docs, which I call minimum viable documentation.)

Ease of getting around

This category combines a couple of easily overlooked areas: navigation and search.

Navigation

• Are your reference docs (Swagger or the like) in a separate location from the rest of the documentation because they were difficult to integrate? If that's the case, reference documentation will be that much harder to find.

• Have you grouped the DevOps-related content together with the API reference, but without mixing in content intended for other users? Non-API docs clutter the user experience with unneeded information -- the folks who consume APIs provided by your product may be completely different from the end users who receive the data from your APIs. If so, keep the documentation sets completely separate.

• Is it possible to get from any page of your site to any other page within one or two clicks?

• Is the documentation organized so simply that users can guess where they need to go most of the time, even if they haven't been there before?

Search

• Can users search the complete content of your API-related docs from one search interface? (If they are searching API reference, can they search all the content, or just the headings and summaries? Some searches only seem adequate until you search for the name of a parameter that you remember using.)

• Is it possible to search only the documentation for the product I'm concerned about, as opposed to all the products and media that you own? Can I narrow the search to just the API docs I'm concerned about?

• If a search gives more than one page of results, is it possible to filter?

Effectiveness

Customers need to know when they look up documentation and code samples, they are getting information that will work. Assuring that the documentation leads to success depends on practices like hands-on testing by authors, running programmatic tests of code samples, and communication with customers (when possible) to verify that how-to articles cover all the necessary use cases.

API design

The usability of the API itself can be improved on two levels.

• The naming of properties and parameters. You're creating a taxonomy that should be understandable, consistent, and predictable for the end user. (There are numerous guides about the subject, online and in books. For example “The Design of Web APIs” by Arnaud Lauret.)

• The workflows (the pattern of requests) required by the API to complete a particular task.

A technical writer can make a significant contribution to API design by reviewing either of these design factors early in the process.