Technical Documentation

Write clear, accurate, and maintainable technical documentation. Adapt style and depth to the document type and audience.

Workflow

Step 1: Determine Document Type and Audience

Identify what kind of documentation is needed:

Step 2: Gather Source Material

Read the codebase to extract accurate information:

# Understand project structure
ls -la
find . -name "*.md" -not -path "*/node_modules/*" | head -20

# Check for existing docs
cat README.md 2>/dev/null
ls docs/ 2>/dev/null

# For API docs: find route definitions
grep -rn "router\.\|app\.\(get\|post\|put\|delete\)" --include="*.ts" --include="*.js" src/
# or for Python
grep -rn "@app\.\(route\|get\|post\|put\|delete\)" --include="*.py" .

# For architecture docs: understand dependencies
cat package.json 2>/dev/null | head -30
cat requirements.txt 2>/dev/null
cat docker-compose.yml 2>/dev/null

• Read the actual code to ensure documentation accuracy.
• Check for existing docs that should be updated rather than duplicated.
• Look at tests for usage examples.
• Check git history for recent changes if updating existing docs.

Step 3: Write the Documentation

Follow the format template for the chosen document type (see Output Format section). Key principles:

Structure: Use headers, lists, and tables to make content scannable. Readers skim first, read second.

Accuracy: Every code example must work. Every command must be copy-pasteable. Wrong docs are worse than no docs.

Completeness: Cover happy path AND edge cases. Document error states, not just success states.

Conciseness: Say what needs to be said, then stop. Long docs go unread.

Step 4: Validate

• Verify code examples by reading the actual source.
• Ensure install/setup instructions match the current project state.
• Check that links and references point to real files.
• Confirm environment variable names match what the code actually reads.

Output Format Templates

README Template

# Project Name

One-line description of what this project does.

## Quick Start

Prerequisites, install, and run in under 60 seconds.

## Overview

2-3 paragraphs explaining the project's purpose, architecture, and key concepts.

## Installation

Step-by-step install instructions with exact commands.

## Usage

Common use cases with code examples.

## Configuration

Environment variables and config options in a table.

| Variable      | Required | Default | Description              |
|---------------|----------|---------|--------------------------|
| DATABASE_URL  | Yes      | -       | PostgreSQL connection URL |

## Development

How to set up the dev environment, run tests, and contribute.

## API Reference

Brief API overview or link to full docs.

## Troubleshooting

Common issues and their solutions.

API Documentation Template

# API Reference

## Authentication

How to authenticate. Include a working curl example.

## Endpoints

### POST /api/resource

Create a new resource.

**Request**
| Field   | Type   | Required | Description         |
|---------|--------|----------|---------------------|
| name    | string | yes      | Name of the resource |

**Response** `201 Created`
```json
{ "id": "abc123", "name": "example" }

Errors

### Runbook Template

```markdown
# Runbook: <Operation Name>

## Overview
What this runbook covers and when to use it.

## Prerequisites
- Access to <system>
- Permissions: <role>

## Procedure

### Step 1: <Action>
```bash
<exact command>

Expected output: <what you should see> If this fails: <what to do>

Step 2: <Action>

...

Rollback

How to undo this operation safely.

Escalation

When and how to escalate if the runbook doesn't resolve the issue.

## Examples

**User**: "Write a README for this project"
**Action**: Read package.json/pyproject.toml for project info, scan src/ for structure, check for existing setup scripts, and write a complete README with install, usage, and development sections.

**User**: "Document the API endpoints"
**Action**: Find all route definitions in the codebase, read request/response types, check middleware for auth requirements, and produce endpoint-by-endpoint documentation with examples.

**User**: "Write a runbook for database failover"
**Action**: Ask about the database setup, document the exact commands for failover, include verification steps after each action, and add rollback and escalation procedures.

**User**: "Create an onboarding guide for new backend engineers"
**Action**: Document local setup, key architectural concepts, important services, common workflows, where to find things, and who to ask for help.

## Best Practices

- Write for your reader, not for yourself. A README for external developers is different from an internal architecture doc.
- Every code example must be tested or verified against the actual codebase. Wrong examples erode trust in all documentation.
- Use consistent terminology. If the codebase calls it a "workspace," don't call it a "project" in the docs.
- Put the most important information first. Readers who need to skim should get the essentials from the first few sections.
- Date or version-stamp docs that are likely to become stale. "Last updated: 2024-01" helps readers judge currency.
- Prefer examples over explanations. Show, then explain if needed.
- Keep runbooks copy-paste ready. An on-call engineer at 3 AM should not have to interpret your prose.
- Use links instead of duplication. If something is documented elsewhere, link to it rather than copying it.
- Include a "Troubleshooting" or "FAQ" section for recurring questions. This reduces support load and helps future readers.