Developer documentation

Developer Documentation

Turn code and accepted decisions into clear, task-oriented documentation that lets a developer understand, run and extend the system without guesswork.

1. Answer five questions before writing

1. Who is the reader? (New contributor, frontend/backend developer integrating an API, operator on call, reviewer.)
2. What concrete task or question do they have?
3. What prior knowledge, tools and access do they start with?
4. Which version and environment does this document apply to?
5. What observable result tells them they succeeded?

2. Choose the right document type (Diátaxis)

Do not mix every purpose into one wall of text; match the structure to the reader's job:

• Tutorial (learning-oriented): a guided, end-to-end first experience with a safe, repeatable outcome. Keep choices and branching out.
• How-to guide (task-oriented): steps to solve a specific problem (How to add a migration, How to register a webhook). State prerequisites, ordered steps, and how to verify the result.
• Reference (information-oriented): exact facts organized like the code or interface—endpoints, parameters, types, configuration keys, defaults, CLI flags, error codes. Complete and scannable, not narrative.
• Explanation (understanding-oriented): why the system is built this way, data flow across boundaries, trade-offs, invariants and constraints.

3. Structure every procedural guide for execution

• Scope and prerequisites: required runtime versions, running services, permissions, working directory and environment variables before step 1.
• Mandatory vs. optional steps: label optional configuration or environment-specific branches explicitly so the main path stays unambiguous.
• Concrete examples and intermediate steps: show realistic inputs, placeholder tokens (<PROJECT_ID>, example.com) and the intermediate step that bridges two components instead of skipping over "glue" configuration.
• Expected outcome and verification: after key steps, show the command, HTTP response, log line or UI state that confirms the step worked.
• Destructive or state-changing commands: state the consequence and the safe target environment (local dev, staging, production) right before the command.

4. Style and clarity (Zinsser & Knuth)

• Write short, direct sentences in active voice. Cut filler, marketing language and vague adjectives.
• Introduce domain terms on first use or link to the project glossary.
• Explain not only what the code does (which the code already shows), but why the boundaries, ordering and constraints exist.
• Never write a "catalog of symbols" that merely restates function names and parameter types without explaining how they fit together or how to use them.

Before you finish

• Reader, task, prerequisites, target version/environment and success check are explicit.
• Document structure matches its purpose (tutorial, how-to, reference or explanation).
• Mandatory and optional steps are distinguished; destructive commands carry warnings.
• Examples use safe test data and consistent placeholders—never real secrets or personal data.
• Unnecessary prose removed; every section helps the reader act or understand.