Skip to content
Developer Experience Docs
The style guide is in beta: content and structure may change.

API documentation principles

These rules apply across every API reference page, whether hand-written or generated from source comments. A reference page has a fixed shape, and each part has its own page of rules:

  • Deprecation notice, first on the page when the element is deprecated (api-002).
  • Intro: the first one or two sentences, reused wherever the element is listed (intros).
  • Overview and remarks: when to use the element, how it relates to its neighbors, and the behavior the signature does not show (overview and remarks).
  • Members, parameters, return values, and errors, one section per public member (members and parameters, return values, and errors and exceptions).
  • Examples, introduced by what they accomplish (api-001 and api-009 on this page).
  • Links to related elements and further reading (refer and link).

Same voice as everything else

Section titled “Same voice as everything else”
api-007 must API docs

Apply the same brand voice principles (clear, concise, helpful) to developer and API documentation as to other content types.

Examples

  • ✓ Use this endpoint to get a user.
  • ✗ The aforementioned endpoint facilitates the retrieval of user entities.

Rationale

API reference documentation 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.

Describe what the example does

Section titled “Describe what the example does”
api-009 should API docs

Introduce a code example by stating what it accomplishes and in what situation, not by naming the call it makes.

Examples

  • ✓ This example shows how to call the create() method when initializing a Component object.
  • ✗ This example calls the create() method.

Rationale

On a reference page the reader already knows which element the example is about. The introduction earns its place by saying what the example achieves and when a reader needs it, which is what decides whether they read the code. code-003 requires the introduction; this rule says what it contains on a reference page.

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 _displayName field populated by UserCacheImpl.

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 an element is deprecated, put the notice first on the page, before the intro. State that the element is deprecated, the version in which it was deprecated if version tracking is used, the replacement with a link, and what developers must do to update their code. Use the form This [kind] is deprecated followed by Use the [replacement] instead.

Examples

  • ✓ This method is deprecated in v2.3. Use the listUsers() method instead, and update callers to handle its paginated response.
  • ✗ Deprecated. Don’t use.
  • ✗ A deprecation note placed after the examples at the end of the page.

Rationale

A developer who hits a deprecated element needs to know what replaces it and how to migrate, before they read anything else on the page; a notice at the end is read after the work is done.

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.

Don’t use “API reference” alone as a noun

Section titled “Don’t use “API reference” alone as a noun”
api-008 should GuidesAPI docsMarketingBlog

Don’t use API reference alone as the noun for the documentation, and don’t pluralize it as API references. Give it a head noun: API reference documentation, API reference content, API reference docs. As a label or a modifier it stays fine: an “API reference” heading, an API reference page.

Examples

  • ✓ Link each type to its API reference page.
  • ✗ Link each type to the API reference.
  • ✓ How to write API reference documentation.
  • ✗ How to write API references.

Rationale

Reference names what the documentation is for, not what it is. Used bare, it reads as trade jargon and gets pluralized into something no reader would say. The head noun makes the phrase concrete.

Applicable rules from other topics

Section titled “Applicable rules from other topics”

Deprecated rules

Section titled “Deprecated rules”
  • api-005 (retired 2026-09-13): “Use gender-neutral pronouns and a diverse set of names when depicting people in documentation examples, and avoid reinforcing stereotypes about job roles.” It restated incl-001, incl-008, and incl-009, which apply to API reference documentation as they do to every content type, and its example pair showed a pronoun violation, not a naming one. The ID stays reserved and is never reused.