docs

Technical Documentation Writer

Different documentation types serve different purposes. The format rules exist because readers come to each type with a specific goal — give them what they came for immediately.

Documentation Types and Rules

README

The README answers: "what is this and can I use it in 2 minutes?"

Rules:

• First sentence: what this IS, not what it will do someday. "A CLI for syncing Obsidian vaults" not "This project aims to..."
• Installation in <5 commands. If it takes more, show the most common path and link to full setup
• One working example before any explanation — show before you tell
• Link to full docs, don't duplicate them

Structure:

# Project Name
One sentence description.

## Install
[<5 commands]

## Quick Start
[One working example]

## [Links to deeper docs if needed]

API Docs

Rules:

• Describe behavior, not implementation — "Returns paginated results sorted by createdAt" not "Calls the database with a LIMIT clause"
• Every parameter: name, type, required/optional, default, what it does
• Every return value: type, shape, what it contains
• One realistic example per endpoint — not a toy example, something close to real usage
• Document the error cases: what fails, what you get back, what to do about it

Parameter format:

name (string, required) — The user's display name. Max 50 characters.
limit (number, optional, default: 20) — Results per page. Max 100.

Architecture Docs

Rules:

• Explain decisions (WHY), not just structure (WHAT). Structure can be read from code. Decisions cannot.
• For each major architectural choice: what was considered, what was chosen, why, what tradeoffs were accepted
• C4 diagrams for system context (level 1: system in its environment) and container diagrams (level 2: major components)
• Keep current — an outdated architecture doc is actively harmful (misleads more than no doc)

Structure:

## Context
[What problem this system solves, who uses it]

## Key Decisions
[Decision record format: what, why, alternatives considered, tradeoffs]

## System Diagram
[C4 context or container diagram]

## Data Flow
[How data moves through the system for the main use cases]

How-To Guides

Rules:

• Task-oriented title: "How to add authentication" not "Authentication"
• Assumes the reader has the prerequisite knowledge — link to it, don't re-teach it
• Steps are ordered by dependency: step N builds on step N-1
• Each step has one action and one expected result

RFC / Design Doc / ADR

For team-facing proposals and records. Ask which type before starting — each has a different section convention.

Type	Use When
RFC	Change isn't decided yet — soliciting feedback before committing
Product design doc	Scoping new work — goals, non-goals, user stories, success metrics
Architecture proposal	System design or pattern change — current state, proposed design, trade-offs, migration
ADR	Decision already made — capture context, decision, consequences

Workflow for proposals/records:

1. Confirm doc type and primary audience (specific team, eng leads, whole org)
2. Ask for context dump — problem, background, constraints, stakeholder concerns
3. Follow the brainstorm → curate → draft → refine loop for each section
4. Start with the section that has the most unknowns; save TL;DR for last
5. After 3 iterations with no changes, ask "what can be removed without losing value?"
6. Reader test: predict 5 questions a reader with no context would ask — does the doc answer them?

RFC/design doc structure:

## TL;DR
[Summary — write last]

## Problem
[What's painful, with real data]

## Proposed Solution
[Scoped, not "change everything"]

## Why Now?
[What triggered this]

## Trade-offs
[Pros AND cons — naming downsides builds trust]

## Alternatives Considered
[What you rejected and why]

## Rollback Plan
[Makes skeptics comfortable]

## Open Questions
[Decision points for the reader — silence in team chat means readers didn't know what to react to]

For docs going into team chat: include a TL;DR at the top suitable for pasting into Slack.

Quality Checklist

Before delivering any docs, verify:

• First sentence tells you what this IS, not what it does someday
• Code examples run without modification (test them)
• All required config / env vars are documented
• Common errors documented with how to fix them
• No passive voice for user actions ("you run" not "the command is run")
• No "simply" / "just" / "easy" — the reader is here because it wasn't obvious
• Links work (check any URLs referenced)
• Consistent terminology throughout (pick one name per concept)

Workflow

1. Identify the documentation type (README, API, architecture, how-to)
2. Ask for any missing context: what's the audience, what do they already know, what do they need to do
3. Draft with type-specific rules applied
4. Run through the quality checklist before delivering

References

Load the template that matches the doc type — all are equal priority, triggered by type alone.

Doc Type	Load when	Reference
ADR	Decision already made — need to capture context and consequences	references/adr-template.md
RFC	Change not decided — soliciting team feedback before committing	references/rfc-template.md
Architecture Proposal	System design or pattern change with trade-off analysis	references/architecture-proposal-template.md
Design Doc	Scoping new work — goals, non-goals, user stories, success metrics	references/design-doc-template.md