documentation-and-adrs

Imported from terminalskills/skills (skills/documentation-and-adrs/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill documentation-and-adrs. Copyright stays with the author (MIT).

Documentation and ADRs

Overview

Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered.

Instructions

Architecture Decision Records (ADRs)

Write an ADR when:

• Choosing a framework, library, or major dependency
• Designing a data model or database schema
• Selecting an authentication or API architecture strategy
• Any decision that would be expensive to reverse

Store ADRs in docs/decisions/ with sequential numbering:

# ADR-001: Use PostgreSQL for primary database

## Status
Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
[Key requirements and constraints that drove the decision]

## Decision
[What was decided and why]

## Alternatives Considered
[Each alternative with pros, cons, and reason for rejection]

## Consequences
[What follows from this decision]

ADR Lifecycle: PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

Don't delete old ADRs — they capture historical context. When a decision changes, write a new ADR that references and supersedes the old one.

Inline Documentation

Comment the why, not the what:

// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

Don't leave TODO comments for things you should just do now. Don't leave commented-out code — git has history.

API Documentation

For public APIs, document with types:

/**
 * Creates a new task.
 * @param input - Task creation data (title required, description optional)
 * @returns The created task with server-generated ID and timestamps
 * @throws {ValidationError} If title is empty or exceeds 200 characters
 * @throws {AuthenticationError} If the user is not authenticated
 */
export async function createTask(input: CreateTaskInput): Promise<Task> {}

README Structure

Every project should cover:

• One-paragraph description
• Quick Start (clone, install, env, run)
• Commands table (dev, test, build, lint)
• Architecture overview with links to ADRs
• Contributing guidelines

Changelog Maintenance

## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)
### Changed
- Task list now loads 50 items per page (was 20) (#126)

Examples

When to Document vs When NOT to

Document:

• Making a significant architectural decision
• Choosing between competing approaches
• Adding or changing a public API
• Known gotchas that could trap future developers or agents

Don't document:

• Obvious code that's self-explanatory
• Throwaway prototypes
• Comments that restate what the code says

Document Known Gotchas

/**
 * IMPORTANT: Must be called before the first render.
 * If called after hydration, causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {}

Guidelines

Common Rationalizations

Red Flags

• Architectural decisions with no written rationale
• Public APIs with no documentation or types
• README that doesn't explain how to run the project
• No ADRs in a project with significant architectural choices

Verification

After documenting:

• 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
• No commented-out code remains