Documentation Standards

Documentation Standards

Purpose

Define language-specific documentation formats, quality standards, and writing principles for generating, auditing, and maintaining code documentation. Apply these standards consistently across all documentation-related operations.

Core Principles

Explain the Why, Not the What

Focus documentation on intent, rationale, and context rather than restating what the code already expresses. A function named calculateTax does not need a description that says "calculates tax." Instead, describe which tax rules apply, what edge cases exist, and why a particular algorithm was chosen.

Weak:

/** Sorts the array. */
function sortUsers(users) { ... }

Strong:

/**
 * Sort users by subscription tier (premium first), then by join date.
 *
 * Premium users appear first to ensure priority support routing.
 * Within the same tier, older accounts take precedence per SLA policy.
 */
function sortUsers(users) { ... }

Use Active Voice

Write descriptions in active voice, present tense. Start function descriptions with a verb.

Completeness Requirements

Document every public API with all of the following:

1. Brief summary -- one sentence stating what the function does
2. Parameters -- every parameter with type, description, default value, and constraints
3. Return value -- type, meaning, and edge-case values (e.g., null when not found)
4. Exceptions/errors -- every error condition with its cause
5. Side effects -- I/O operations, state mutations, event emissions, network calls
6. At least one example -- realistic, runnable usage demonstrating the common case

Mark internal/private APIs as lower priority but still document non-trivial logic. When a private function contains a complex algorithm, business rule, or non-obvious workaround, treat it as high priority regardless of visibility.

Language Format Quick Reference

For complete templates, before/after examples, and per-language standards checklists, see references/language-formats.md.

Documentation Quality Severity Levels

Use these severity levels when auditing or reporting documentation issues.

Critical -- Must Fix Immediately

Issues that cause incorrect understanding or hide dangerous behavior.

High -- Fix This Sprint

Issues that cause confusion or leave important gaps.

Medium -- Fix This Quarter

Issues that reduce documentation usefulness.

Low -- Fix When Convenient

Issues that affect polish and completeness.

Documentation Writing Standards

Specificity Over Generality

Replace vague descriptions with concrete, measurable statements.

Terminology Consistency

Maintain consistent terminology within a project:

• Choose one term per concept and use it everywhere (e.g., always "user ID" not sometimes "userId" and sometimes "user identifier")
• Match parameter names in documentation to parameter names in code exactly
• Use the same tense and grammatical structure across all descriptions in a file

Example Quality Standards

Write examples that meet these criteria:

1. Realistic -- use plausible data, not foo/bar/baz
2. Runnable -- include imports, setup, and assertions where possible
3. Progressive -- show the common case first, then edge cases
4. Self-contained -- each example should work independently without external context

/**
 * @example
 * // Fetch active users with pagination
 * const page = await fetchUsers({ status: 'active', limit: 25, offset: 0 });
 * console.log(page.users.length); // 25
 * console.log(page.total);        // 1042
 *
 * @example
 * // Handle empty results
 * const empty = await fetchUsers({ status: 'banned', limit: 10 });
 * console.log(empty.users);  // []
 * console.log(empty.total);  // 0
 */

Documentation Drift Detection

When auditing or updating documentation, watch for these drift patterns:

When drift is detected, update the documentation to match the implementation, not the other way around. The code is the source of truth. Never modify code to match outdated documentation unless the documentation reflects the intended design and the code has a bug.

Format Selection Rules

When generating or auditing documentation, select the format by these rules:

1. Follow existing project conventions -- if the project already uses a documentation style, match it exactly
2. Follow language conventions -- if no project style exists, use the language standard (JSDoc for JS/TS, Google-style for Python, Javadoc for Java, etc.)
3. Prefer structured formats -- use tagged formats (@param, Args:) over unstructured prose for API documentation
4. Match tooling expectations -- choose formats compatible with the project's documentation generator (TypeDoc, Sphinx, Javadoc tool, godoc, etc.)

Module and File-Level Documentation

Beyond function-level documentation, ensure each file or module has a top-level description covering:

• Purpose -- what this module is responsible for
• Dependencies -- key external dependencies and why they are needed
• Usage -- how other modules should import and use this module
• Architecture notes -- where this module fits in the broader system

Place module-level documentation at the top of the file, before any imports or declarations. For languages that require a package declaration first (Java, Go), place the module comment immediately above the package statement.

Additional Resources

Reference Files

For detailed per-language templates and quality audit procedures, consult:

• references/language-formats.md -- Complete documentation templates, before/after examples, and standards checklists for JSDoc, Python, Javadoc, Go, Rust, C#, Ruby, and PHP
• references/quality-checklist.md -- Completeness, accuracy, and consistency audit procedures with documentation drift detection and writing quality criteria