Technical Writing for Developers
debt(d9/e5/b7/t5)
Closest to 'silent in production until users hit it' (d9). There are no detection_hints or tools listed. Poor technical writing produces no compiler errors, no linter warnings, and no runtime exceptions — the damage (confusion, rewrites, repeated support questions, outage recurrence) only surfaces when a new developer joins, a system needs maintenance, or an incident repeats. The feedback loop is entirely human and typically arrives months or years later.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix gives a minimal README template (one sentence, copy-paste commands, one link), but the common_mistakes reveal that fixing bad documentation across a codebase — reordering content to match reader needs, replacing vague verbs, adding working examples, integrating doc review into code-review checklists — spans multiple documents, multiple PRs, and process changes. It is not a one-line patch, but it does not require full architectural rework either.
Closest to 'strong gravitational pull' (b7). Documentation (or its absence) shapes how every future maintainer understands, modifies, and extends a system. As noted in why_it_matters, undocumented systems get rewritten from scratch; a missing postmortem means the same outage recurs. The burden is cross-cutting: every work stream — onboarding, incident response, API integration, RFC discussion — is slowed or derailed by poor documentation conventions established early.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field states the canonical trap explicitly: developers assume technical writing is about literary quality (writing well, being comprehensive, being eloquent), when it is actually about usefulness (clear over clever, short over comprehensive, one working example over three paragraphs of prose). This is a well-documented gotcha that most developers learn only after producing unhelpful docs and observing the downstream confusion.
Also Known As
TL;DR
Explanation
Technical writing is the difference between code that an organisation can maintain and code that only its author understands. Core principles: lead with the reader's goal, put the summary first, use active voice, keep sentences short, show examples, and favour concrete nouns over abstract ones. Common artefacts a developer writes include: READMEs (setup + one happy-path example + links), API reference (endpoint, params, example request, example response, errors), design docs / RFCs (context + problem + options + decision + consequences), postmortems (timeline + impact + root cause + mitigation + action items), and inline comments (explain *why*, not *what*). Good technical writing follows the inverted-pyramid structure of journalism — the reader can stop at any point and still have the most important information. Every minute spent on clarity saves many minutes of interruption later.
Common Misconception
Why It Matters
Common Mistakes
- Writing docs in the order the feature was built instead of the order the reader needs — start with what the reader wants to do, not how it was implemented.
- Using vague verbs like 'handles', 'manages', 'deals with' — say what it actually *does*: returns, writes, deletes, validates.
- Explaining the obvious and skipping the unobvious — readers need to know the gotchas, not that 'this function takes two arguments'.
- Letting docs drift out of date — add doc review to the code-review checklist; an out-of-date doc is worse than no doc.
- Not showing a working example first — readers copy the example, tweak, and learn; reference material they read later.
Avoid When
- A throwaway experiment you will delete tomorrow — but be honest that it is actually throwaway and not creeping production code.
When To Use
- Any code or system that someone other than you will touch — even yourself in six months.
- Designing a change significant enough to need discussion — write the RFC first, argue about the doc not the code.
- After an incident — the postmortem is the durable artefact.