Documentation Principles

Effective documentation practices for software engineering teams.

Diátaxis Framework — Four Modes of Documentation

Key insight: Don't mix modes. A tutorial that explains why fails at teaching how. A reference that includes how-to fails at lookup.

README Essentials

Every repository needs a README that answers:

# Project Name

**One-line description** — What does this do?

## Quick Start
```bash
# Minimal commands to run locally
git clone ...
cd project
make dev

Architecture Overview

• High-level diagram (text or image)
• Key components + interactions
• Link to Architecture Decision Records

Development

• Prerequisites (versions, tools)
• Local setup
• Running tests
• Code style / linting

Deployment

• Environments (staging, prod)
• Deploy process
• Rollback process

Configuration

• Environment variables (with examples)
• Feature flags
• Secrets management

Monitoring & Debugging

• Logs location
• Metrics dashboard links
• Common issues / troubleshooting

Contributing

• Branch strategy
• PR process
• Code review guidelines

License & Contacts

---

## API Documentation

### OpenAPI/Swagger
- **Source of truth** — Generate from code (annotations, decorators) or write by hand
- **Versioned** — Match API versions
- **Examples** — Real request/response examples for every endpoint
- **Authentication** — Document auth schemes clearly

### API Docs Best Practices
- Keep in sync with code (CI check)
- Document error responses (not just success)
- Include rate limits, pagination, filtering
- Version in URL (`/v1/`) or header
- Deprecation policy documented

---

## Architecture Decision Records (ADRs)

See Architecture Decision Records for full process.

**Quick template**:
```markdown
# ADR-XXX: Decision Title

**Status**: Accepted | Superseded | Deprecated
**Date**: YYYY-MM-DD

## Context
[What problem? What constraints?]

## Decision
[What are we doing?]

## Consequences
- **Pros**: [...]
- **Cons**: [...]
- **Risks**: [...]

Code Documentation

Comments: The "Why", Not the "What"

# BAD: What the code does (obvious from reading)
user = fetch_user(id)  # Fetch user by ID

# GOOD: Why this approach / non-obvious constraint
# We use a stale read here because strong consistency
# adds 200ms latency and the user profile tolerates
# eventual consistency for this display path.
user = fetch_user_stale_read(id)

Docstrings / JSDoc / etc.

• Public APIs: Required — consumers need this
• Internal: When non-obvious — complex algorithms, business rules
• Keep synced — outdated docs are worse than none

Self-Documenting Code > Comments

• Names reveal intent: calculate_discounted_price > calc(x, y)
• Small functions with clear names
• Types as documentation (TypeScript, Python type hints, Rust)

Technical Writing Principles

Clarity

• Active voice: "The service processes requests" not "Requests are processed by the service"
• Present tense: "Returns" not "Will return"
• Specific: "Timeout after 30 seconds" not "Timeout after a while"
• Concrete examples over abstract descriptions

Audience Awareness

• Tutorial: Assume zero knowledge; explain every step
• How-to: Assume basic competence; focus on the specific task
• Reference: Assume expertise; be complete and precise
• Explanation: Assume curiosity; provide context and rationale

Structure

• Inverted pyramid — Most important info first
• Scannable — Headers, bullets, code blocks, tables
• Progressive disclosure — Summary first, details on demand
• Cross-references — Link related docs (wikilinks in Obsidian, URLs elsewhere)

Documentation as Code

Treat Docs Like Code

• Version controlled (same repo as code)
• Reviewed in PRs — Docs changes = code changes
• Tested — Link checkers, spell check, example validation
• Built — CI publishes to docs site (Docusaurus, MkDocs, GitBook, etc.)

Automation

• markdownlint — Style consistency
• lychee / markdown-link-check — Dead link detection
• vale — Prose linting (style, terminology, readability)
• Examples in docs = integration tests

Knowledge Management

Internal Wiki / Knowledge Base

• Ownership — Every page has an owner/team
• Expiration — Pages have review dates; stale = flagged
• Search — Full-text search essential
• Structure — Consistent hierarchy; avoid deep nesting

Runbooks / Playbooks

For operational procedures: - Trigger — What initiates this runbook? - Symptoms — How to recognize the situation - Diagnosis — Steps to identify root cause - Resolution — Step-by-step fix with commands - Verification — How to confirm fixed - Escalation — When to page whom

Onboarding Documentation

• Day 1: Account setup, tool access, repo clone, first build
• Week 1: Architecture tour, key systems, deploy process, on-call intro
• Month 1: Deep dives, shadowing, first independent task

Documentation Anti-Patterns

Tooling Recommendations

Related Notes

• Architecture Decision Records — ADR process and templates
• Technical Writing — Style guide deep dive
• Knowledge Management — Wiki, runbooks, onboarding
• Git Workflow — PR process includes doc review
• Engineering Culture — Documentation as culture

Sources: Diátaxis (diataxis.fr), Google Technical Writing, Microsoft Writing Style Guide, Write the Docs, AWS Documentation Best Practices, Docusaurus, MkDocs