2learn

Technical Writing

What it is

Technical writing is documentation a stranger can follow: specifications, READMEs, runbooks, architecture notes and decision records. The artefact is the document, and the only test that matters is whether somebody who did not write it can act on it without asking a question.

Why it matters

Documentation is read at the worst moment: during an incident, on a new joiner’s first week, six months after the author left. The cost of a bad document is paid entirely at those moments, which is why the effort belongs in structure and audience rather than in prose style. It is also the only durable form of the team’s memory — a conversation is not available to the person on call at 3 a.m., and the code does not explain why it is shaped the way it is.

In this track

  1. Structure of a spec or README (04-product-process/08-technical-writing/01-structure-of-a-spec-or-readme) — the sections a reader expects and the order they need them in.
  2. Editing for the reader (04-product-process/08-technical-writing/02-editing-for-the-reader) — cutting, ordering and testing the document on someone who is not you.

Prerequisites

None.

Go deeper

Analytics cookies are set only if you allow them. Nothing is loaded, and nothing is sent, until you choose.