The Ideal API Reference

Accurate, Clear, and Unambiguous Content

While complete content is essential, if the API user can’t understand the content, or worse, if it’s inaccurate, the writer might as well have not written it. When we talk about accuracy, we’re referring to the correctness of the content. Too often, the content contained in an API reference isn’t correct or doesn’t work for the user. Sometimes the content is accurate, but unintelligible to anyone other than the person who wrote it, and in other situations, the content can have multiple interpretations, most of which are wrong.

Achieving accuracy and clarity, and avoiding ambiguity is difficult, even for good API writers. Typically, issues with accuracy, clarity, and ambiguity arise due to one or more of the following situations:

• Inaccurate, incomplete, or unintelligible API specification (spec)
• Not enough access to the API designers to get content
• Not enough access to the API designers to review documents
• Non-writers writing significant sections of content that ends up in the API reference
• Not enough reviewers outside of the API design team

The following sections provide some guidance on how API providers and API writers can overcome these issues.

Assign a Senior API Writer at the Beginning of the Design Process

An ideal API reference is typically based upon a good spec, so it’s important at the beginning of an API development project to ensure that the team develops and maintains a really good specification. To accomplish this, an organization can assign a senior API writer at the beginning of the project (even if only on a part-time basis) to help create/maintain the spec. When there’s a professional API writer involved at the beginning, that person can ensure clarity and accuracy in the specification from the start. The technical writer can also maintain a technical glossary (which we talk about later in this article).

Other benefits to having a senior API writer on the API design team include:

• The writer of the API reference might be the first person to consider the entire public API (the layer exposed to the API user) from an API user’s perspective and can point out incongruities from that perspective.
• The members of a product team generally specialize in particular parts of the product or areas of functionality, and aren’t as familiar with areas outside of their specialty; the API writer has a complete view of the API.
• The API architects are often more concerned with implementation choices than with the completeness and consistency of the public API, and that’s exactly what the API writer is paid to worry about.
• Focusing on developing the spec or an API reference gives the API writer an opportunity to share their observations about the API user layer, representing the perspective of the target users. With these observations and perspectives, the API design team can decide how to improve the API design early in the process, when the cost of doing so is relatively low.

Generate Reference Material from Source Code

For efficiency and accuracy, many API development teams generate their reference documentation from comments in source code as a part of the development workflow. API writers achieve the best quality API reference if they can work directly on the comments in the code. When editing generated documents, an API writer does the following:

• Examines the comments for unclear or incomplete descriptions common to initial cycles of API documentation, and adds complete descriptions for elements that the authors considered “self documenting” or obvious.
• Ensures completeness by checking that all input and output values are mentioned and described, and that defaults are provided for optional elements.
• Revises existing comments for consistent style and terminology.

Granting permissions and privileges to API writers for commenting yields high return with low risk. Writers who are capable of describing and explaining APIs are equally capable of both editing comments in code and working with version-control tools. For developers who are concerned about giving API writers access to their source files, some tools limit editing access to only comment lines.

Some API development teams don’t allow writers any degree of write access to source code. Instead, the API writer does the documentation work in a separate branch where changes are permitted. In this situation, the team needs to allocate extra resources to perform several follow-up tasks, including:

• Merging comment and other documentation changes into the main line
• Regenerating documents
• Scheduling additional rounds of reviewing

An integrated development environment (IDE) or an editor made code-aware with plugins can have an embedded documentation generation feature or site generator. Examples include Antora for AsciiDoc, JSDoc 3, and the Javadoc Generation wizard in Eclipse.

Use Other Existing Material as a Resource for Content

When the project is underway, different groups within the API provider (such as the design, development, architecture, and marketing teams) can often provide considerable information about the API, even if it isn’t yet in a form that’s useful to users. The content tends to be focused on implementation choices and details, rather than the user layer and usage model. Existing material can include:

• Product requirement documents or design documents
• Presentations, ideally with audio and video recordings or detailed speaker notes to provide a full explanation of the slides
• Product/customer support documents or knowledge bases
• Marketing overviews or white papers
• Existing interactive or developer-created documentation, beyond what’s in the source code
• Content from important team email streams

From this material, experienced API writers can extract concepts, diagrams, terminology, and possibly even chunks of text and examples. With these elements, writers can fill in some holes in the reference or create a first pass at usage-oriented content. These elements can also form a basis for further questions to ask the subject-matter experts (SMEs).

Collect Content from Subject-Matter Experts

Subject-matter experts (SMEs) are typically members of the API development team. API architects and developers know the technical architecture and how the API is built, operates, and is intended to be used. SMEs can also be product managers, project managers, and QA and customer support team members who specialize in this product.

Throughout the documentation process (although primarily in the early stages), an API writer has to solicit information from SMEs. The writer’s job is to focus on the usage model and to work with the SMEs to provide context, identify and correct inconsistencies, and complete content where a deeper explanation is necessary.

SMEs are often under too much pressure to have a lot of time to talk with writers about the product, so it’s essential for the writer to use every minute with an SME wisely. As such, it’s critical for the API writer to be prepared before approaching an SME.

In the best of all situations, the writer should have attempted to collect and understand all the available pieces of information listed in Complete Content before interviewing the SME. When possible, an interview with an API SME should be more about getting clarification and filling in the gaps rather than collecting a lot of raw information that can be gleaned from other sources.

API writers need to prepare their questions carefully, and ask them coolly and neutrally. It’s also important for writers to be confident enough to ask clarifying questions when something doesn’t make sense; it really might not make sense.

Get SMEs to Review the Documentation

It’s critical for the API design team (and SMEs in general) to review the API documentation. It’s the only way to ensure accuracy and completeness. But getting access to an SME’s time is tough. To make it worse, if SMEs are given a lot of documentation to review at one time, their eyes start to glaze over and they stop seeing the errors. Again, there are a number of techniques that help address these issues:

• Split the review into small chunks. Try to keep the review time to less than 30 minutes. This might mean that you can only send out one or two functions at a time for review.
• Make sure that the content is really ready for a review. Before you send out the content, clean it up a bit. Is it devoid of typos? Does it reflect the recent changes that the writer knows about? Does it use the appropriate terms, formatting, etc.? The cleanliness of the writing is incredibly important, because the writer needs to keep the SME focused on what they need to review—the technical content. They shouldn’t be distracted by extraneous errors.
• Send out a review to one person at a time early in the review process. Until the primary SME has reviewed the content and deemed it technically correct, don’t show it to others.
• When you get corrections from the reviewer, apply them globally. Nothing makes SME reviewers more upset than correcting the same error, term, or change multiple times. Note: This might take some thought on your part.
• Start the review process early! Don’t wait until the last minute when everyone is under the gun to get the product out the door.

Get Outside Reviewers to Review the Documentation

SME reviewers are necessary for getting the technical content accurate. However, you also need reviewers outside the team who aren’t familiar with the API reference, as they can point out where the content isn’t clear, and give you a user perspective.

These outside reviewers can be customer app developers, sys admins, support personnel, and field engineers. Maybe the writer can use customer support personnel within the organization, or a “friendly” customer (like a Beta tester) who can serve this purpose. In any case, the team needs to find someone outside the development team who doesn’t know what the words are supposed to mean. Writers outside the project can potentially be good reviewers, as long as they have the coding skills necessary to understand how to use the API. And also note that, by the end of the project, the writers working on the documentation are too indoctrinated in the API to be objective reviewers.