A Great Developer Experience Requires Great Documentation

[jeofoyster]

After a developer learns about your API—maybe by searching online, or maybe by organization mandate—the first thing they’ll always do is look for your documentation. Before webinars, sample applications, hackathons, or training, your documentation is the first and best opportunity to win your customers to your API.

What makes good documentation? Technical references are the bare essentials, but the more material you can sustainably provide, the better experience your potential and existing customers will have. This then leads to:

• Faster time to adoption
• Well-validated use cases for your product
• Reduced customer support burden
• Stronger affinity for your platform
• Community goodwill and referrals to other developers

Three Key Categories

So what’s ideal? We’ve broken it down into three key categories of documentation: Product & Context, Technical Reference, and Tutorials & Cookbooks.

Product & Context

If you treat your APIs as a product, supported and maintained by your API program teams, then you should prepare materials that “sell” the APIs as a product. This is true for all audiences of your API program. External developers choose your offering rather than a competitor’s; internal developers choose your tools rather than building yet another copy of the same system.

Most of the time, this documentation should be written by your API Product Owner, because their expertise lies in defining and articulating value, and working with customers to solve their problems.

Value Proposition and Marketing Content

First, write a sentence that hooks your audience with the single greatest benefit they’ll get from your platform. That could be making money, or simplifying a complex technology, or reaching a greater audience. Additional marketing content can include examples of how others have used your APIs, transparent pricing and/or feature availability information, comparisons to other solutions, and potentially a high level roadmap (especially for internal audiences).

Credibility-Boosting and/or Core Asset Context

One Apigee customer’s APIs feature agriculture-specific weather and modeling data, and the company’s value proposition lies in the unique approach to data processing and global availability. The “About Our Data” content they created served both as a differentiator to other weather data sources available, and explained the basic science of how the data was derived to answer any credibility questions before they arose.

Onboarding Overview and How to Get Help

Once you’ve hooked your audience, they will immediately want to play with the API. Provide a very clear “Get Started” page that details the process for getting an API key especially if your process is manual or requires special pre-approval. And ultimately, no matter how good your documentation, your customers will always have questions; provide an obvious “Help” page that connects to or describes your preferred support channels.

Technical Reference

The most important piece of documentation—and probably the simplest to create—describes all the ins and outs of your API endpoints. Rarely are two, beautifully RESTful APIs built with exactly the same assumptions, behaviors, or configuration; providing even the basic details of your API—like what HTTP status codes to look for or how authentication works—can endear your product to your audience.

Conventions

Every API is built with certain assumptions in mind, and getting your audience on the same page prevents a lot of confusion. Since most of these details are likely documented in your own standards playbook, creating a customer-facing version of it should be straightforward. A page of design conventions should include:

• Affirmation of RESTful principles like what HTTP Verbs mean (link to outside tutorials for more)
• What is “in contract” and thus will not change without a version, such as URI paths, payload property names, response formats, and HTTP Status Codes
• What is not in contract and might change without a version, such as sort ordering, error messages, pagination details, new payload properties, etc.
• Authentication scheme details
• Rate limiting information
• Common designs for pagination, sorting, filtering, and flexible payloads
• What HTTP Status Codes you’ll return for certain error conditions

Publishing your design conventions, along with setting expectations around deprecation and versioning, can mitigate customer concerns or panic when the time comes to make API changes.

Detailed Technical Reference

Be sure that every endpoint, every parameter, and every payload is described for your developers, especially if there are any caveats, usage and formatting requirements, or downstream impacts. If an API has special HTTP Headers or Status Codes that aren’t described as conventions, then include that information as well. Detail is essential here as much as anywhere else, so find a balance between reference data and more verbose context.

This material can be written by a technical writer or even a technical product manager or developer evangelist, but the best practice is to create reference material following the OpenAPI specification at the same time you’re building your API proxies or target services. Then, not only is your documentation tied to your source code branching and versioning strategy, but you can also automatically generate visually appealing, executable documentation through tools like SmartDocs or Swagger UI.

Tutorials and Cookbooks

Your customers may or may not already know much about your data, domain, or even how to use RESTful APIs. This third category of documentation seeks to build a stronger relationship with your audience by helping them improve their craft, as well as improve their understanding of your API’s complexities.

Tutorials

While it may feel remedial to provide basic tutorials on topics like RESTful APIs or parsing JSON, this type of content—or at least linking to third party sources—can accelerate your customers’ progress. But more than the basics, if there is any concept or topic that would benefit your developers’ understanding of your domain, then you should include it as a topical tutorial. For example, the Ag-Tech Apigee customer referenced earlier included tutorials on certain scientific concepts, which their customers use to build more relevant interfaces.

Cookbooks

Some APIs expose complex domains or systems. These might require multiple API calls to accomplish a task (e.g., new account setup, portfolio management, etc), there may be very specific data formatting requirements, or there could be dependencies across other domains. In these cases, you should provide simplified step-by-step recipes that a developer can follow to achieve a given task.

These how-to guides typically include an ordered list of steps, each with a sample API call, for example:

1. Retrieve the user profile using this API call:
   
   GET /users/{userId}/accounts
   
   
2. Choose an account from the list and then retrieve that information:
   
   GET /accounts/{id}/overview
   
   
3. Test a transaction before committing it to catch errors sooner:
   
   POST /accounts/{id}/transactions?mode=test
   
   

If you can provide a working, copy-and-pastable example of the recipe, that’s even better.

Be Comprehensive, Contextual, and Colloquial

Finally, across all three categories there are certain best practices for how you write your documentation. No one really likes reading formal specifications; plus you should never assume your audience is made up of computer scientists or even formally trained programmers. Write in a friendly, human, jargon-free voice. Reference the readily available guidelines for Writing for the Web. If it starts to sound like a “for Dummies” book, that’s a good thing.

Assume your audience has never worked in your domain before; you don’t have to teach a university course on the topic but provide enough background or example code that they can jump start in spite of their lack of context.

And apart from domain knowledge, plainly describe the important facets of your technology. Explain the purpose for each endpoint in its description, including when they would—or should not—use it. Warn them about edge cases or known bugs that might trip them up, because they will find them anyway.

While creating comprehensive documentation will take extra time at the launch of your program, it pays dividends several times over if you do it well. Time and again, we’ve seen documentation be the make or break factor when it comes to choosing an API. Giving your customers everything they need at their fingertips will keep your team focused on building new value. And building trust with your developers endears them to you for their current project, for any future project, and at a future employer where they’ll need your services again.