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:
So what’s ideal? We’ve broken it down into three key categories of documentation: Product & Context, Technical Reference, and Tutorials & Cookbooks.
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.
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:
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.
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:
If you can provide a working, copy-and-pastable example of the recipe, that’s even better.
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.