# Documentation Principles

Effective documentation practices for software engineering teams.

---

## Diátaxis Framework — Four Modes of Documentation

| Mode | Purpose | Audience | Example |
|---|---|---|---|
| **Tutorial** | Learning-oriented — "Show me how" | Newcomers | "Build your first API" |
| **How-to Guide** | Problem-oriented — "How do I...?" | Practitioners | "Configure Redis caching" |
| **Reference** | Information-oriented — "What is...?" | All | API specs, config options |
| **Explanation** | Understanding-oriented — "Why...?" | Decision-makers | "Why we chose event-driven" |

**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:

```markdown
# 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/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"
```python
# 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

| Anti-Pattern | Fix |
|---|---|
| **Docs in separate wiki** | Docs in repo with code; CI publishes |
| **Outdated docs** | Doc review in PR; automation checks |
| **Wall of text** | Structure, headers, diagrams, code blocks |
| **No examples** | Every feature needs a working example |
| **Assumed knowledge** | Define terms; link prerequisites |
| **Single giant page** | Split by Diátaxis mode; link together |
| **No search** | Enable full-text search on published docs |

---

## Tooling Recommendations

| Category | Tools |
|---|---|
| **Static Site Generators** | Docusaurus, MkDocs, Astro Starlight, VitePress, GitBook |
| **API Docs** | Swagger UI, Redoc, Scalar, Stoplight Elements |
| **Diagrams** | Mermaid (in markdown), PlantUML, Excalidraw, Structurizr |
| **Linting** | markdownlint, vale, lychee, cspell |
| **Wiki** | Notion, Confluence, GitBook, Outline, Wiki.js |

---

## Related Notes

- [[Architecture/Architecture-Decision-Records]] — ADR process and templates
- [[Documentation/Technical-Writing]] — Style guide deep dive
- [[Documentation/Knowledge-Management]] — Wiki, runbooks, onboarding
- [[DevOps/Git-Workflow]] — PR process includes doc review
- [[Methodologies/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*