jamestorrevillas Technical Documentation
Documentation Philosophy
Write for the reader who is in a hurry and under stress.
Good documentation answers the question before the reader finishes asking it. Every doc should have a clear audience and a clear job to do.
Documentation Types & When to Use Each
| Type | Purpose | When to Write |
|---|---|---|
| README | Project overview + quickstart | Every project, day 1 |
| Architecture Doc | How the system is designed and why | Before building complex systems |
| Runbook | Step-by-step operational procedures | For anything ops needs to do repeatedly |
| API Reference | Endpoint contracts | When exposing an API to others |
| ADR | Why a significant decision was made | After every major technical decision |
| Changelog | What changed between versions | Every release |
| How-To Guide | Task-oriented instructions | When users need to do a specific thing |
README Template
# [Project Name]
One-sentence description of what this does and why it exists.
## Prerequisites
- [Dependency 1] v[X.X]
- [Dependency 2]
## Getting Started
\`\`\`bash
# Clone and install
git clone [repo]
cd [project]
npm install
# Configure
cp .env.example .env
# Edit .env with your values
# Run
npm run dev
\`\`\`
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| DATABASE_URL | Yes | PostgreSQL connection string |
| JWT_SECRET | Yes | Secret for JWT signing |
## Architecture
[Brief overview or link to architecture doc]
## Testing
\`\`\`bash
npm test # Unit tests
npm run test:e2e # End-to-end tests
\`\`\`
## Deployment
[How to deploy or link to runbook]
## Contributing
[How to contribute or link to guide]
Architecture Document Structure
# Architecture: [System/Feature Name]
## Overview
[2-3 sentences: what this does and why it exists]
## Goals & Non-Goals
**Goals:** [what this system is designed to achieve]
**Non-Goals:** [what it explicitly does NOT cover]
## Architecture Diagram
[ASCII diagram or Mermaid diagram]
## Components
### [Component 1]
- **Responsibility:** [what it does]
- **Interface:** [how others interact with it]
- **Dependencies:** [what it needs]
## Data Flow
[How data moves through the system for key use cases]
## Key Decisions
[Link to ADRs or inline rationale for major choices]
## Known Limitations
[Honest description of current constraints]
Runbook Template
# Runbook: [Operation Name]
**When to use:** [Trigger condition]
**Time required:** ~[X minutes]
**Who can run this:** [Role/permission needed]
## Prerequisites
- [ ] Access to [system]
- [ ] [Tool] installed
## Steps
1. [First action — be specific, include exact commands]
\`\`\`bash
[exact command]
\`\`\`
Expected output: [what success looks like]
2. [Next step]
## Verification
[How to confirm the operation succeeded]
## Rollback
[If something goes wrong, how to undo]
## Escalation
If stuck after [X minutes]: contact [person/team]
Writing Style Guidelines
- Active voice — "The system sends a notification" not "A notification is sent"
- Present tense — "The function returns..." not "The function will return..."
- Specific — "Run
npm install" not "Install dependencies" - Short sentences — one idea per sentence
- Examples — show, don't just tell
- Maintain it — outdated docs are worse than no docs. Update docs in the same PR as code changes.
AI-Optimized Documentation (for RAG systems)
Write docs to be machine-readable as well as human-readable:
- Consistent terminology throughout
- Each section is self-contained (can be read without other sections)
- Include explicit labels: "Purpose:", "When to use:", "Example:"
- Modular structure — individual chunks make sense in isolation