technical-documentation

Technical Documentation

Purpose

Write documentation that answers the question the reader actually has. Most documentation fails because it mixes four incompatible purposes into one document and serves none of them.

When to Use

• Writing a README, a getting-started guide, or API reference.
• Documentation that exists but that nobody can use.
• Documenting a library, a service, or an internal system.
• Auditing documentation for gaps.

Capabilities

• The four types: tutorial, how-to, reference, explanation — and keeping them apart.
• README structure.
• API reference: complete, accurate, and generated where possible.
• Runnable examples.
• Keeping documentation accurate as the code changes.

Inputs

• The system, and who reads about it.
• The questions readers actually arrive with.
• The existing documentation, and where it fails.

Outputs

• Documentation organized by reader intent.
• Examples that run.
• A README that gets someone to a working state.

Workflow

1. Identify the reader's question — "How do I start?" (tutorial), "How do I do X?" (how-to), "What are the parameters?" (reference), "Why is it built this way?" (explanation). These are four different documents. Mixing them is why documentation is unusable.
2. Write the README to a first success — Install, minimal working example, then links. A reader should be running something within two minutes. Everything else is a link.
3. Make the examples runnable — Copy, paste, and it works. An example with an elided ... or an undefined variable is a broken promise.
4. Generate the reference — From the code, from the types, from the OpenAPI spec. Hand-written reference documentation is wrong within a month.
5. Test the tutorial on a stranger — Someone who has never seen the project. Every place they get stuck is a defect in the document.

Best Practices

• The single most common documentation failure is mixing a tutorial with a reference. A reader trying to get started does not want a complete list of options; a reader looking up a parameter does not want a narrative.
• A README that opens with a philosophy section has lost the reader. Open with what it is, in one sentence, and how to install it.
• Every code example must run as written. Test them in CI — documentation examples rot faster than the code.
• Write the error cases. "What happens when the token is invalid" is the question people arrive with, and it is almost never documented.
• Document the why, separately. A reader who understands the design makes better decisions than one who has memorized the API.
• Do not document what the code says. Document what the code cannot say: the constraints, the reasons, the gotchas.