Career & Craft
Technical Writing
Writing that gets an engineering decision made or a system understood: design docs, RFCs, ADRs, READMEs, postmortems. The craft is front-loading — problem and proposal first, justification after — and writing for the reader who skims. A good design doc compresses weeks of meetings into an afternoon read.
Purpose
Past a certain team size, writing is how engineering actually happens: a design doc collects context, forces vague ideas to commit to specifics, and lets ten people review asynchronously what a meeting would have half-resolved. It is also the only channel to the most important audience — people who are not in the room, including everyone who joins after you leave. Unwritten decisions get re-litigated; written ones compound.
When to Use It
Design docs and RFCs for choices worth arguing about; ADRs — a page recording a decision, its context and its alternatives — for the trail of why things are the way they are; READMEs that get a stranger to a running system without a guide; postmortems; and the daily forms, PR descriptions and issue reports, where five clear sentences routinely save a reviewer half an hour.
Trade-offs
Documents rot — the code moves and the prose does not, and a wrong doc misleads with more authority than no doc — so write more where change is slow (decisions, architecture) and less where it is fast (implementation detail, which belongs near the code). Writing costs real time, and heavyweight processes can become consensus theatre; the doc should be as long as the decision is expensive, and no longer.
Implementation
Lead with the conclusion: problem, proposal, then rationale — structure for the skimmer with headings that summarise and a summary that stands alone. State rejected alternatives and why; that section does the most work in review and the most good two years later. Keep docs in the repo or wiki where they are found, date them, and review high-stakes writing like code. One revision pass for clarity pays for itself immediately.