Technical Writing & Documentation

Every system carries knowledge that exists only in the heads of the people who built it: why this queue has a retry limit of three, which service to restart first, what happens if you run the migration twice. Documentation is the practice of moving that knowledge somewhere durable — and doing it in a form people will actually read at the moment they need it.

The engineering framing is more useful than the writing-craft one. Docs have a build, a review process, and a decay rate. They go stale when they sit apart from the code, so they belong in the repo, reviewed in pull requests, and checked by CI — the docs-as-code model. And they serve distinct jobs: a README gets someone started, an ADR preserves a decision's reasoning, a runbook gets a system back up at 3 a.m., and a changelog tells consumers what broke. Merging them produces a document that does none of them.

TL;DR

• Docs-as-code: Markdown in the repo, reviewed in PRs, built and link-checked in CI.
• Documentation has four distinct modes — tutorial, how-to, reference, explanation — and mixing them is the most common structural failure.
• A README answers what it is, how to run it, and how to contribute. Nothing else.
• ADRs capture why a decision was made, including options rejected — the thing git history never explains.
• Runbooks are written for a tired person under pressure: numbered, literal, copy-pasteable.
• Changelogs are a contract with consumers; breaking changes need migration steps, not just a version bump.
• Diagrams belong in version control as text (Mermaid, D2, C4), not as screenshots of a whiteboard.

The Four Modes

Featured Topics

Process & Tooling

• Docs-as-Code — Markdown in the repo, PR review, CI link checking, and versioned docs
• Docusaurus & Docs Sites — Building and deploying a documentation site
• Documentation Style Guides — Voice, terminology, and enforcing consistency with linters

Document Types

• READMEs — The front door of a repository
• Architecture Decision Records — Capturing why, not just what
• Runbooks — Operational procedures for incidents and routine tasks
• Release Notes & Changelogs — Semantic versioning, Keep a Changelog, and migration guides

Visuals

• Technical Diagrams — Mermaid, C4, sequence diagrams, and diagrams-as-code

Common Questions

Isn't good code self-documenting?

Code documents what it does, and at its best how. It cannot document why a different approach was rejected, what the operational failure modes are, which constraint made an ugly workaround necessary, or how a newcomer should get started. Those are exactly the questions that take up an experienced engineer's time when they go unrecorded. Self-documenting code removes the need for comments explaining mechanics; it doesn't remove the need for ADRs, runbooks, or a README.

How do I keep documentation from going stale?

Reduce the distance between the docs and the thing they describe. Keep them in the same repository so a change and its documentation land in one pull request. Generate reference material — API schemas, CLI help, config options — from source rather than transcribing it. Run link checking and code-sample compilation in CI. Then accept that some decay is inevitable and prune aggressively: a page marked as archived is far better than a plausible-looking page that is quietly wrong.

Who should write the documentation?

The person who did the work writes the first draft, because they hold the context. Someone unfamiliar reviews it, because they're the only one who can detect assumed knowledge. Where a dedicated technical writer exists, the highest-value use of them is structure, consistency, and the reader-facing surfaces — not being the sole author. Treating docs as a separate team's job reliably produces documentation that lags the system.

What's the minimum viable documentation for a project?

A README that gets someone running locally, a CHANGELOG if anyone else depends on your releases, and a runbook for anything you'd be paged about. Add ADRs once decisions start being revisited by people who weren't in the room. That's genuinely enough for most projects; volume is not the goal.

Does AI-generated documentation help?

It's good at the mechanical layer — drafting reference material from code, expanding terse notes, keeping tone consistent, and flagging gaps. It's unreliable at exactly the parts that matter most: intent, tradeoffs, and operational reality, which aren't recoverable from source. Use it to lower the cost of a first draft, then have a human supply the reasoning and verify every command and code sample actually runs. Confidently wrong documentation is worse than none, because readers trust it.

Related Hubs

• Open Source — Contributing guides and project documentation
• DevOps — Runbooks, postmortems, and operational readiness
• Backend Development — API documentation and OpenAPI
• Architecture — Decision records and system design docs
• Engineering Leadership — Written culture and asynchronous communication