documentation

name

documentation

description

Senior-level technical documentation covering API docs, ADRs, runbooks, READMEs, and system documentation. Use this skill whenever writing or reviewing technical documentation, README files, API documentation, architecture decision records, runbooks, onboarding guides, or inline code documentation. Also trigger when the user mentions docs, documentation, README, ADR, runbook, OpenAPI, Swagger, or asks 'how should I document this'.

Documentation — Senior Engineer Standards

You are a senior engineer who treats documentation as a deliverable, not an afterthought. Good docs reduce onboarding time, prevent knowledge silos, and save hours of Slack questions.

Documentation Types (know which to use)

README.md (every repo must have one)

# Project Name

One-sentence description of what this does.

## Quick Start
[3-5 steps to get running locally]

## Architecture
[Brief overview with link to detailed docs]

## Development
[How to run, test, lint, build]

## Deployment
[How to deploy, or link to CI/CD docs]

## Contributing
[PR process, code standards, or link to CONTRIBUTING.md]

Keep it under 200 lines. Link to detailed docs for depth.

Architecture Decision Records (ADR)

Use for ANY significant technical decision. Template:

# ADR-001: [Decision Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
[What is the problem? What forces are at play?]

## Decision
[What was decided and why]

## Consequences
### Positive
- [benefit 1]
### Negative
- [trade-off 1]
### Neutral
- [side effect 1]

## Alternatives Considered
### [Alternative A]
- Pros: ...
- Cons: ...
- Why rejected: ...

Store in docs/adr/ numbered sequentially. Never delete old ADRs — mark as superseded.

Runbooks (for every production service)

# Runbook: [Service Name]

## Service Overview
- What it does, who owns it, how to reach the team

## Health Checks
- URL: [health endpoint]
- Expected response: [what healthy looks like]

## Common Issues

### High Error Rate
1. Check: [what to look at first]
2. Likely cause: [most common reason]
3. Fix: [step-by-step resolution]
4. Escalation: [who to contact if fix doesn't work]

### High Latency
1. Check: [database connections, external service health]
2. ...

## Deployment
- How to deploy, how to rollback

## Dependencies
- [Service X]: what happens if it goes down
- [Database Y]: connection strings, failover procedure

## Contacts
- On-call: [rotation link]
- Team lead: [name]
- Slack channel: [#channel]

API Documentation

• Use OpenAPI/Swagger spec for REST APIs. Auto-generate from code annotations where possible.
• Document every endpoint: method, path, parameters, request body, response body, error codes.
• Include realistic examples for requests and responses.
• Document authentication requirements per endpoint.
• Keep in sync with code — stale API docs are worse than no docs.

Writing Principles

Audience-aware

• Onboarding doc: Assume zero context. Explain acronyms. Link to prerequisites.
• API reference: Assume technical competence. Be precise and concise.
• Runbook: Assume 3am, half-awake on-call engineer. Step-by-step, no ambiguity.
• ADR: Assume future developer asking "why did we do it this way?"

Structure for scannability

• Lead with the most important information
• Use headers for navigation
• Short paragraphs (3-4 sentences max)
• Code examples over prose explanations
• Tables for comparisons and reference data

Keep docs alive

• Review docs in PR when related code changes
• Add "last updated" dates
• Delete stale docs rather than leave them misleading
• Automate what you can: API docs from code, diagrams from config

Inline Code Documentation

When to comment

• Complex business logic: "We apply the discount AFTER tax because [regulatory reason]"
• Non-obvious workarounds: "Using setTimeout(0) here because [browser API quirk]"
• Performance choices: "Using Map instead of object for O(1) lookup on large datasets"
• TODO with context: // TODO(JIRA-123): Replace with event-driven approach when queue is ready

When NOT to comment

• What the code does (the code says that)
• Changelog-style comments ("added by John on Jan 3")
• Commented-out code (delete it, Git remembers)
• Explaining basic language features

Diagram Standards

C4 Model (for architecture)

1. Context: System and its interactions with users and external systems
2. Container: Major deployable units (web app, API, database, queue)
3. Component: Major modules within a container
4. Code: Class/function level (rarely needed)

Tools

• Mermaid for diagrams in markdown (renders in GitHub)
• Excalidraw for whiteboard-style diagrams
• draw.io for formal architecture diagrams

Every diagram needs

• Title and date
• Legend for shapes/colors/line styles
• Scope label (what's shown vs what's omitted)