Documentation Standards

Provides: Document skeletons for the common types, a comment taxonomy, and clarity rules for maintainable technical docs.

Quick Reference

Golden Rule: Document what helps the reader act correctly

Document:

• Purpose, setup, usage, public contracts, and common failure modes
• Why a non-obvious decision was made
• Constraints, compatibility notes, and migration steps
• Known limitations and workarounds, with the reason

Avoid:

• Restating what the code plainly says
• Large background sections the reader does not need
• Stale examples or unverified commands

Principles: Audience first, show rather than tell, keep current

Document Skeletons

Pick the shape that matches the artifact instead of growing a README until it covers everything.

README (orientation and quick start):

# Project name

One or two sentences explaining what this is for.

## Quick start
## Usage
## Development
## Contributing

Guide (task-based procedure):

## Goal
## Prerequisites
## Steps
## Verify
## Troubleshooting

API reference (per endpoint or function):

## Endpoint or function

Purpose, inputs, response or return value, errors, example, compatibility notes.

Decision record or spec:

## Context
## Decision
## Alternatives considered
## Consequences
## Rollout or migration

A guide without a Verify step leaves the reader unsure whether it worked. A decision record without Alternatives considered cannot be revisited later, because the reasoning is gone.

Examples in Docs

Show real usage with expected output, not abstract placeholders:

### POST /api/users

Create a new user.

**Request:**
{ "name": "John", "email": "john@example.com" }

**Response:**
{ "id": "123", "name": "John", "email": "john@example.com" }

**Errors:**
- 400 - Invalid input
- 409 - Email already exists

Every documented contract should list inputs, outputs, and errors. Errors are the part most often omitted and most often needed.

Comments

Add a comment for:

• Invariants the code relies on but does not state.
• Workarounds, with the condition for removing them.
• Surprising side effects or ordering requirements.
• Links to an external algorithm, spec, ticket, or incident.

// Discount tiers are contractual: Bronze 5%, Silver 10%, Gold 15%.
const discount = getDiscountByTier(customer.tier);

// The upstream API returns null instead of [] on an empty result.
// Remove once vendor ticket SUP-4821 ships.
const items = response.items || [];

Do not comment what clear code already says:

// ❌ Increment i
i++;

// ❌ Get user
const user = getUser();

Checklist

Before finishing documentation work:

• The reader can tell whether this document applies to them
• The document uses the skeleton matching its type
• Commands and examples are current, or explicitly marked unverified
• Public contracts list inputs, outputs, and errors
• Comments explain invariants, workarounds, and ordering, not the obvious
• Every workaround comment states when it can be removed
• Code changes in this task are reflected in the docs in the same change
• Terminology is consistent with the surrounding docs

See also

• Load standards-markdown for the formatting and layout rules.
• Load role-technical-writer when the audience or information architecture is still undecided.
• Load standards-api-design when documenting a public or partner contract.