Documentation

Documentation is the interface between your present self and future readers — teammates, open-source contributors, and the version of yourself that returns to a codebase after six months. Good documentation is not comprehensive coverage of every line; it is the right information, in the right place, at the right level of detail. The most common failure modes are too little (the reader has no map) and too much (the reader cannot find the signal in the noise).

Types of Documentation

README — the entry point. Every repository needs one. It should answer: what is this? how do I run it? how do I contribute? A good README takes a new engineer from zero to running the project in under 15 minutes. It is not a changelog, a full API reference, or a tutorial.

Architecture Decision Records (ADRs) — lightweight documents that capture why a significant architectural decision was made, along with the alternatives considered and the tradeoffs accepted. ADRs answer the most common question in any mature codebase: “why is it done this way?”

API documentation — generated or hand-written reference for public interfaces. Describes what each function, method, or endpoint accepts, returns, and throws. This is the “what” layer; the ADR is the “why” layer.

Inline comments — annotations within the code explaining non-obvious intent, constraints, or warnings. These should be rare in well-named code. When present, they explain the why, not the what.

When to Write Docs vs Trust the Code

Clear code with well-named functions and types is always preferable to a comment that explains unclear code. The question is not “should I document this?” but “who is the reader and what do they need?”

JSDoc for Public APIs

JSDoc is the standard format for documenting TypeScript/JavaScript functions and types. TypeScript-aware editors surface JSDoc inline as you type, making it the most impactful documentation you can write.

/**
 * Formats a monetary amount for display in the given locale.
 *
 * @param amountCents - The amount in the smallest currency unit (e.g. cents for USD).
 * @param currencyCode - ISO 4217 currency code (e.g. "USD", "EUR", "GBP").
 * @param locale - BCP 47 locale string. Defaults to the user's browser locale.
 * @returns A formatted string, e.g. "$12.50" or "€12,50".
 * @throws {RangeError} If `currencyCode` is not a valid ISO 4217 code.
 *
 * @example
 * formatCurrency(1250, "USD");      // "$12.50"
 * formatCurrency(1250, "EUR", "de-DE"); // "12,50 €"
 */
export function formatCurrency(
  amountCents: number,
  currencyCode: string,
  locale?: string
): string {
  return new Intl.NumberFormat(locale, {
    style: "currency",
    currency: currencyCode,
  }).format(amountCents / 100);
}

Document every exported symbol in a shared library or package. For application-internal code, document functions whose purpose or constraints are non-obvious.

Architecture Decision Records

An ADR is a short document (typically 1–2 pages) that records a significant architectural decision. The most widely used format is the MADR (Markdown Architectural Decision Records) template by Michael Nygard:

# ADR-0003: Use PostgreSQL as the primary database

## Status
Accepted

## Context
The application needs to store relational data with complex queries.
We evaluated SQLite (too limited for concurrent writes), MongoDB (mismatch
for relational data), and PostgreSQL.

## Decision
We will use PostgreSQL 16 with Prisma as the ORM.

## Consequences
- ✅ Full ACID compliance, excellent JSON support, mature ecosystem
- ✅ Prisma provides type-safe queries and migration tooling
- ❌ Requires a running Postgres instance for local development (solved with Docker)
- ❌ More complex than SQLite for simple CRUD; acceptable given our scale

Store ADRs as files in the repository (docs/decisions/) so they are versioned alongside the code. A decision that was made and then reconsidered should be marked “Superseded by ADR-0012” — never deleted.

Keeping Docs Up to Date

Stale documentation is worse than no documentation — it actively misleads. Strategies for keeping docs current:

• Treat docs like tests. If a PR changes behaviour, updating the relevant docs is part of the definition of done, not optional.
• Automate what you can. Generated API docs (TypeDoc, JSDoc tooling) stay in sync automatically. OpenAPI specs generated from route definitions cannot drift from the routes.
• Docs-as-code review. Include a documentation check in your PR template: “Does this change require a README or ADR update?”
• Remove dead docs. A deleted feature’s documentation should be deleted with it.

Further Learning

Search these terms to go deeper:

• “MADR Michael Nygard Architecture Decision Records” — the original ADR format and a large community collection of examples
• “Divio documentation system” — a framework dividing docs into tutorials, how-to guides, reference, and explanation
• “TypeDoc TSDoc” — the standard for JSDoc in TypeScript projects and how to generate HTML from it
• “Docs as code Anne Gentle” — treating documentation with the same rigor as code (version control, review, CI)
• “Write the Docs community” — the largest community of technical writers and documentation practitioners

Documentation

Documentation is a note to future readers — teammates, and the you who comes back in six months having forgotten everything. Good docs aren’t “explain every line”; they’re the right info in the right place. Too little leaves people lost; too much buries the useful bits.

The main kinds of docs

• README — the front door of a project. Answers: what is this, how do I run it, how do I contribute? A newcomer should go from zero to running in ~15 minutes.
• API docs — what a function/endpoint takes and returns. (Often written as JSDoc, see below.)
• Inline comments — short notes in the code for anything surprising. Explain the why, not the what.
• Decision records (ADRs) — a short note explaining why a big choice was made.

Comment the why, not the what

Clear code beats a comment explaining unclear code. Save comments for reasoning the code can’t express:

// ❌ just repeats the code
// loop over users
for (const user of users) { ... }

// ✅ explains a non-obvious reason
// Process newest first so the dashboard shows recent activity immediately.

JSDoc: docs your editor shows you

Writing a JSDoc comment above a function makes your editor show helpful hints when anyone uses it:

/**
 * Formats an amount as currency.
 * @param cents - amount in the smallest unit (e.g. cents)
 * @param currency - ISO code like "USD"
 * @example formatCurrency(1250, "USD") // "$12.50"
 */
export function formatCurrency(cents, currency) { ... }

High value for shared/reusable functions.

Decision records (ADRs)

When your team makes a notable choice (“we picked PostgreSQL over MongoDB because…”), jot a short note: the context, the decision, and the trade-offs. Months later, when someone asks “why is it done this way?”, the answer’s written down.

In one sentence

Documentation serves future readers: a README to get started, API docs (JSDoc) for reusable functions, inline comments for the why, and decision records for big choices — and keeping docs current (or deleting stale ones) matters more than having lots of them.

Want to go deeper?

Switch to Expert mode above for the full ADR template, the docs-per-reader table, and strategies to keep docs in sync with code.