api-007 must API docs Apply the same brand voice principles (clear, concise, helpful) to developer and API documentation as to other content types.
API documentation principles
These rules apply across every API reference page, whether hand-written or generated from source comments. Guidance for specific parts of a reference page — method descriptions, parameter tables, and cross-references — lives on the other pages in this section.
Same voice as everything else
Section titled “Same voice as everything else”Examples
- ✓ Use this endpoint to get a user.
- ✗ The aforementioned endpoint facilitates the retrieval of user entities.
Rationale
API reference is still read by people, so the same clarity and helpfulness that guide other content apply here.
Include a code example
Section titled “Include a code example”api-001 should API docs Include a code example in each reference article illustrating how to use the programming element.
Examples
- ✓
copyFile(src, dest)— Copies a file. Example:await copyFile('report.txt', 'backup/report.txt') - ✗
copyFile(src, dest)— Copies a file.
Rationale
A working example shows how the element is actually called, which the signature alone does not convey.
Review generated doc comments
Section titled “Review generated doc comments”api-003 should API docs Review auto-generated documentation comments for quality; remove internal implementation details not appropriate for end users, and supplement missing information important to developers.
Examples
- ✓ Returns the user’s display name.
- ✗ Getter for the internal
_displayNamefield populated byUserCacheImpl.
Rationale
Auto-generated reference carries internal detail and gaps, so review keeps the published docs accurate and useful to callers.
Explain deprecations fully
Section titled “Explain deprecations fully”api-002 should API docs When something is deprecated, specify the replacement, note the version in which it was deprecated if version tracking is used, and explain what developers must do to update their code.
Examples
- ✓ Deprecated in v2.3. Use
listUsersinstead, and update callers to handle its paginated response. - ✗ Deprecated. Don’t use.
Rationale
A developer who hits a deprecated element needs to know what replaces it and how to migrate, or the deprecation just blocks them.
Inclusive people in examples
Section titled “Inclusive people in examples”api-005 should API docs Use gender-neutral pronouns and a diverse set of names when depicting people in documentation examples, and avoid reinforcing stereotypes about job roles.
Examples
- ✓ When Amal shares a file, their teammates get a notification.
- ✗ When the developer finishes his code, he calls
submit().
Rationale
Example code is read widely, so neutral pronouns and varied names keep it inclusive without distracting from the API.
Lowercase, hyphenated filenames
Section titled “Lowercase, hyphenated filenames”api-006 should API docs Use lowercase, hyphen-separated filenames for documentation files; use only standard ASCII alphanumeric characters.
Examples
- ✓
get-started-auth.md - ✗
GetStarted_Auth (v2).md
Rationale
Lowercase, hyphenated, ASCII filenames are portable across systems and produce clean, predictable URLs.