📋 Technical Documentation Types

Main documentation types: API documentation (endpoint reference), README (project overview and setup), Architecture Decision Records (ADRs) (design decisions), Runbooks (operational procedures), Post-incident reports (retrospective analysis), RFCs (proposals for technical changes), User guides (how-to documentation), Changelogs (version history), Technical specifications (detailed design documents). Each has a distinct structure and audience.

An ADR documents a significant architectural decision for future reference. Structure: Title (use numbers: "ADR-001: Use PostgreSQL for main database"), Status (Proposed / Accepted / Deprecated / Superseded), Context (why this decision was needed), Decision (what was decided), Consequences (trade-offs and implications). ADRs create institutional memory and prevent re-litigating past decisions when team members change.

A runbook is a step-by-step operational guide for routine or emergency procedures. Good runbooks include: objective (what problem this solves), prerequisites (tools, access, knowledge required), step-by-step instructions with exact commands, expected outputs at each step, troubleshooting for common failure points, escalation path if the runbook fails, and a revision history. Write for someone with the skills but unfamiliar with this specific system.

An engineering RFC (Request for Comments) is an internal design proposal document where engineers describe a proposed change and solicit team feedback. It typically includes: motivation, proposed solution, alternatives considered, and open questions. Unlike Internet RFCs (IETF standards documents), engineering RFCs are informal, team-specific, and don't require formal voting. They create a record of design thinking and facilitate asynchronous technical discussion.

A technical specification describes WHAT the system should do — requirements, interfaces, constraints, expected behaviours. It's usually written before development. A design document describes HOW the system will be built — architecture, algorithms, data models, trade-offs. Specifications define the contract; design documents explain the implementation approach. Some documents combine both.

PIR structure: (1) Incident summary (what, when, duration, impact); (2) Timeline (chronological events with timestamps in UTC); (3) Root cause analysis (underlying cause, not just trigger); (4) Contributing factors (systems, processes, culture that contributed); (5) What went well (for morale and reinforcement); (6) Action items with owners and deadlines. Use blameless language — focus on systems and processes, not individual errors.

API documentation vocabulary: endpoint (URL path), method (HTTP verb: GET, POST, PUT, DELETE), request/response body (payload), path parameter (/users/{id}), query parameter (`?sort=asc`), authentication (API key, OAuth, JWT), rate limiting (max requests per interval), pagination (how to page through results), deprecation notice (planned removal), status codes (200 OK, 404 Not Found, 500 Internal Server Error).

Good README structure: (1) Project name and one-line description; (2) Badges (build status, coverage, version); (3) Overview — what it does and why; (4) Prerequisites — what you need before installing; (5) Installation — step-by-step commands; (6) Usage — most common examples with expected output; (7) API reference (or link to docs); (8) Contributing guidelines; (9) Licence. Lead with the most useful information — most readers never scroll past the fold.

A changelog records version-to-version changes. Use the Keep a Changelog format: sections for Added, Changed, Deprecated, Removed, Fixed, Security. Each version has a heading with version number and date. Follow semantic versioning: MAJOR (breaking changes), MINOR (new backwards-compatible features), PATCH (bug fixes). Always have an [Unreleased] section at the top. Update the changelog as part of the PR, not as an afterthought before release.

Widely used guides: Google Developer Documentation Style Guide (free online, widely referenced), Microsoft Writing Style Guide, Apple Style Guide, The Chicago Manual of Style (for formal publications). Key principles shared across guides: use active voice, write in second person ("you"), use present tense, prefer simple words, write short sentences, and put the most important information first. These principles apply to API docs, READMEs, and internal wikis.