Technical Handoff Documentation

Write docs that actually get someone unstuck. The test of technical documentation is simple: can a competent person with zero prior context read it and become productive without asking you questions? Most docs fail this because they're written by someone who forgot what it's like not to already know.

The reader-first principle

Write for the specific person who will read this: a new hire, a coworker taking over, or future-you who forgot everything. Assume they're smart but have zero context on THIS project. Every assumption you leave implicit becomes a question they have to interrupt someone to answer - which defeats the purpose of documentation.

Document types and what each needs

README (project front door)

The most-read doc. Someone lands on the repo - what do they need immediately?

1. What is this?        - One paragraph. What the project does and why it exists.
2. Status               - Is it prod, WIP, deprecated? Don't make them guess.
3. Quick start          - Copy-pasteable steps to run it locally. The #1 thing people want.
4. Prerequisites        - Exact versions (Node 20+, Python 3.11, etc.). Vague versions waste hours.
5. Setup / installation - Step by step, actually tested. Include env vars needed.
6. Usage                - How to use it once running. Key commands/endpoints.
7. Project structure     - What lives where (brief map of key directories).
8. Configuration        - Env vars, config files, what each does.
9. Deployment           - How it gets to production (or link to the runbook).
10. Troubleshooting     - Common errors and fixes. Grows over time.

Not every README needs all ten. A library needs usage + API; a service needs setup + deployment. Match the sections to what a reader of THIS project actually needs.

Handoff document (project transfer)

When one person hands a project to another. Beyond the README, cover:

- Current state         - What's done, what's in progress, what's broken right now
- What's left           - Remaining tasks, ideally prioritized, with context on each
- Known issues / gotchas - The things that will bite them that aren't obvious from code
- Key decisions          - Why things are the way they are (saves them re-litigating)
- Access & credentials   - What accounts/services/keys they need (NEVER paste secrets - say where to get them)
- Contacts              - Who to ask about what (you, vendors, other teams)
- The "if I had more time" list - What you'd do next

The gotchas and key-decisions sections are the highest-value part of a handoff - they transfer the context that isn't in the code.

Runbook (operational procedures)

For recurring operational tasks (deploy, rollback, incident response):

- When to use this      - The trigger/situation
- Prerequisites          - Access, tools needed
- Steps                 - Exact, numbered, copy-pasteable. No ambiguity under pressure.
- Verification          - How to confirm it worked
- Rollback              - How to undo if it goes wrong
- Escalation            - Who to call if stuck

Runbooks are read during stress (things are down). Optimize for zero ambiguity, not elegance.

API documentation

For each endpoint:

- Method + path         - GET /api/v1/users/:id
- What it does          - One line
- Auth required         - What kind
- Parameters            - Each param: name, type, required?, description
- Request example       - Actual example with realistic values
- Response example      - Actual JSON, success case
- Error cases           - Status codes and what they mean
- Rate limits / notes   - Anything else that bites people

Writing rules

• Show, don't describe. A copy-pasteable command beats a paragraph explaining what to type.
• Exact versions and values. "Node 20.x", not "recent Node." Vagueness costs hours.
• Test your own instructions. If you can, run the setup steps fresh. Docs that don't work are worse than no docs - they destroy trust.
• Front-load the common case. What 90% of readers need goes first. Edge cases go later.
• Explain the why for non-obvious choices. "We use X because Y" prevents someone undoing a deliberate decision.
• Keep it scannable. Headers, code blocks, short sections. People scan docs, they don't read prose.
• Never paste secrets. Say where to obtain credentials (password manager, vault, a person), never the actual keys/passwords in the doc.

The gotchas section is gold

The single highest-value thing in any handoff is the list of non-obvious traps:

• "The build fails silently if you don't set X"
• "This service must start before that one"
• "The staging DB has different schema - don't test migrations against prod data"
• "That function looks unused but the cron job calls it"

These are the things that would take the next person days to discover and cost you a 2am call. Capture them explicitly.

Hard rules

• Never include actual secrets, passwords, API keys, or tokens in documentation. Reference where to get them securely instead.
• Don't document aspirational behaviour - document what the code actually does now. Note WIP clearly.
• If you're unsure how something works, flag it as "unverified - confirm before relying on this" rather than guessing confidently.