documentation-and-adrs

Documentation and ADRs

Records decisions and documents the why — context, constraints, trade-offs, and rejected alternatives that code alone cannot express.

Overview

Code tells you what was built. Documentation tells you why it was built that way, what alternatives were rejected, and what constraints governed the decision. The most valuable documentation captures the reasoning, not the mechanics.

This skill covers four documentation layers, from most to least strategic:

Core principle: document decisions, not mechanics. A comment explaining why a rate limit uses a sliding window is valuable. A comment that says // Increment counter by 1 above counter += 1 is noise.

When to Use

• Making a significant architectural decision (framework, database, protocol, infra)
• Choosing between competing approaches with meaningful trade-offs
• Adding or changing a public API
• Shipping a feature that changes user-facing behavior
• Onboarding new team members (or agents) — they need the why, not just the code
• When you find yourself explaining the same thing repeatedly — write it down once
• Any decision you expect someone to question in 6 months

Do NOT Use For

• Obvious code: // Increment counter above counter++ — restates the code
• Throwaway prototypes that will be deleted in days
• Code-level docstrings — those belong in the code, not in separate docs
• Tutorials or blog posts — instructional content is not technical documentation
• Legal documents — privacy policies, terms of service
• Marketing materials — landing pages, product brochures

Process: Documentation-Driven Development

Write documentation before code — it forces clarity and surfaces assumptions early.

Step 1 — Write the ADR First

Before making a significant architectural decision:

1. Identify the decision drivers — what's the problem, what forces are at play?
2. List at least 2-3 viable alternatives including "do nothing"
3. Evaluate each: pros, cons, risks, opportunity cost
4. State the decision and the single most important reason for it
5. Log the consequences — positive AND negative (accept the trade-offs)

Best practice: 10 minutes writing an ADR prevents a 2-hour re-litigation debate later.

Step 2 — Write README / API Docs Before Implementation

1. Draft the README from the user's perspective — if you can't describe what the system does in prose, you can't code it
2. Write the OpenAPI spec before implementing endpoints — review the contract with consumers first
3. Update the changelog entry as part of every PR — no merged PR without one

Step 3 — Add Inline Docs During Implementation

Comment the why, not the what:

• Bad: // Fetch user by ID above db.users.findById(id)
• Good: // Use findById instead of findOne because user IDs are unique and a missing user should throw, not return null

Step 4 — Verify

Run the verification checklist below before closing any documentation task.

ADR Template (Progressive)

Start minimal; add depth only when the decision warrants it.

Minimal ADR (for quick, low-risk decisions)

# ADR-NNNN: [Title]

## Status
[proposed | accepted | superseded by ADR-NNNN | deprecated]

## Context
[Problem and constraints — 2-3 sentences]

## Decision
[What we decided, in one sentence]

## Rationale
[Why this over alternatives — 2-3 sentences]

## Consequences
[What this means going forward — 1-2 bullet points]

Full ADR (for significant decisions with lasting impact)

For complex decisions, use the template in references/adr-template.md which includes: Context and Problem Statement, Decision Drivers, Considered Options with detailed pros/cons, Decision Outcome with positive/negative consequences and mitigations, Implementation Plan, and Links.

ADR Lifecycle

PROPOSED → ACCEPTED → (SUPERSEDED by ADR-NNNN or DEPRECATED)

• Never delete ADRs. When a decision changes, write a new ADR that supersedes the old one.
• Rejected ADRs are still valuable — they prevent re-litigating the same question.

When to Write an ADR

• Choosing a framework, library, or major dependency
• Designing a data model or database schema
• Selecting an authentication strategy
• Deciding on an API architecture (REST vs GraphQL vs tRPC)
• Choosing between build tools, hosting platforms, or infrastructure
• Any decision that would be expensive to reverse

Documentation Layers in Detail

README Structure

Every README must answer, in order:

API Documentation

• REST: Use OpenAPI 3.1 as the canonical spec — generate human-readable docs from it. Document method, path, parameters, auth, request/response examples, errors, rate limits
• GraphQL: Use schema introspection. Every type, field, and mutation must have a description in the schema itself
• Never maintain API docs and API specs separately — they will diverge

Inline Documentation

• Comment invariants, gotchas, and non-obvious constraints — not what the code does
• Document the reason for a non-obvious approach, not the approach itself
• If you need >3 lines of comment to explain a block, extract it into a well-named function

Changelogs

Follow Keep a Changelog format with Added, Changed, Deprecated, Removed, Fixed, Security sections. Never use a catch-all "Misc" category. Include diff links at the bottom.

Common Rationalizations

Red Flags

• Architectural decisions with no written rationale — if the team can't point to an ADR for a major choice, that choice is undocumented
• Public APIs with no documentation — consumers can't integrate without guessing
• No ADRs in a project with significant choices — no ADR for a database choice, auth strategy, framework selection
• Documentation that restates code instead of explaining intent — // Increment counter by 1 is worse than no comment (it's visual noise)
• Stale documentation that contradicts code — actively misleading; worse than missing docs
• A single person owns all the documentation — when they leave, the knowledge leaves
• ADRs that list options but skip the rationale — "we chose PostgreSQL" without explaining why not MySQL, CockroachDB, SQLite, etc.
• Changelog entries that mirror git log — "Fixed bug" is not a changelog entry; "Fixed race condition in payment processing (#1234)" is

Verification

Before completing any documentation task:

• [ ] ADRs exist for all significant architectural decisions
• [ ] README covers quick start, commands, and architecture overview
• [ ] API functions have parameter and return type documentation
• [ ] Known gotchas are documented inline where they matter, not restating the code
• [ ] No commented-out code remains
• [ ] No hardcoded credentials, tokens, or internal IPs in any doc
• [ ] Links are tested and work (relative links for internal, absolute URLs for external)
• [ ] Code blocks have language specifiers and produce correct output when run
• [ ] The document answers why (rationale/context), not just what (mechanics)
• [ ] Acronyms are expanded on first use
• [ ] Architecture decisions list the alternatives considered and the reason for rejection
• [ ] Old ADRs are never deleted — superseded ADRs get a status update and link to the new one
• [ ] The changelog entry is written as part of the PR, not after merge
• [ ] One person is not the sole owner of documentation — ownership is distributed

References

• references/adr-template.md — Full ADR template with decision drivers, considered options, mitigations, and implementation plan
• references/readme-template.md — README structure template
• references/api-docs-checklist.md — API documentation completeness checklist

Platform Compatibility Notes