Course Intermediate

Technical Writing and Documentation

By the end of this course

Separates document types by audience and purpose
Writes API reference and tutorial text with different structures
Versions documentation alongside code and keeps it current

Start course

Document Types

The separation of product, developer, and support content; the separate functions of tutorial, how-to, explanation, and reference; repository documents; endpoint and error documentation layout; what release notes mean to the reader; and the symptom-cause-remedy structure.

01 The Scope of Technical Writing A document's number is not its length but the number of claims it carries: four types carry 56 claims, the claims spread across the signature, flow, name, and concept surfaces as 22, 16, 7, and 11, 17 of them are embedded in a runnable example, and a single change on the signature surface drops 22 claims and drops 17 of them silently.
02 Tutorial, How-To, Explanation, and Reference The four types write the same subject with separate purposes and go stale at separate speeds: a single signature change drops 13 of reference's 15 claims by version two, leaving 2, while explanation keeps 11 of 12 — a 6.875-times gap; four of six reader questions land on one type, two land on none.
03 Repository Documents The readme, the contribution guide, and the architecture decision record start at the same version and collapse at separate speeds: all three lose their first claim at version two, but the first two halve by version three while the decision record halves at version twelve, and ten of its twelve stale claims are silent.
04 API Reference 13 of the reference's 15 claims are bound to signature, and a hand-written reference is left at 0/15 by version six; a generated one is left at 13/15 at the same version, the 2 unrecoverable claims sit on the name surface, and because reference carries no example every one of its stale claims is silent.
05 Release Notes The four types describe the product as it is today and none carries time; the raw change list dates 17 of 56 stale claims by version twelve and 0 of the silent ones, while a note that writes what each entry falsifies dates 56 of 56 and 39 of 39 silent ones.
06 Troubleshooting Content A reader arriving with a symptom reaches only 8 of a concept-first text's 17 defects and meets 8 of 51 decisions (0.1569); a symptom-cause-remedy layout reaches all 17 at once and meets 51, but the 39 silently stale claims produce no symptom at all and stay outside troubleshooting too.

Writing Discipline

Writing prerequisite assumptions explicitly, building scannable text, term consistency and voice unity, runnable and verifiable examples, and diagrams serving the text.

01 Audience Definition An unwritten prerequisite assumption does not make a claim false, it makes it unreadable; of the 18 claims still true at the third version, the number readable for the new reader is 3 with no audience definition and 18 with it fully written.
02 Structure and Headings Heading layout measures the distance between the reader's question and its answer; across thirty-six visits, headingless text takes an average of 26.38 steps, type-headed 7.29, two-tier 7.00, and the two-tier layout pays for that gain by carrying 24 silently stale headings at the sixth version.
03 Style Guide A style guide is not a list of mandates but a document that states what each rule measures; when the same concept is called by two names, the reader can find only 25 of 56 claims, 52 stay ambiguous, and 23 of the 31 claims a rename scan misses are silent.
04 Examples and Code Snippets A claim embedded in a runnable example makes noise when it goes stale, one that is not embedded makes none; 17 of 56 claims are embedded, and of the 56 claims stale at the twelfth version, 39 are silent — 0.6964.
05 Use of Visuals What sets a diagram's rate of staleness is not the drawing style but the surface it is bound to: an interface diagram goes wrong at the second version, a concept diagram at the twelfth; since a diagram cannot be run, every stale claim it carries is silent, and a mixed diagram silences all 56 of 56 claims by the twelfth version.

Documentation Operations

Versioning documentation and folding it into the review process, source-to-reference generation approaches, detecting and tracking the life cycle of aging content, and turning support requests into documentation gaps.

01 Docs Alongside Code Versioning documentation in the same repository as code leaves twelve versions of stale debt at 300/672; bringing it into review as well drops that to 43/672; on two surfaces review does not see, 15 claims stay silently stale.
02 Documentation Production Approaches Production is not a single thing: generation from a markup language saves no surface at all, generation from source keeps 22 claims true at version twelve, and it cannot touch the 23 claims on the name and flow surface.
03 Staleness and Audit At version twelve, 56 of 56 claims are stale and 39 are silent; the silence ratio is 0.6964, and finding the silent ones is measured by the per-claim reading cost a documentation audit pays.
04 Feedback Loop Silent staleness becomes visible only when the reader reports it: 240 visits expose 31 of 39 silent claims, all 39 require 960 visits, and cost per report climbs from 5.0 to 24.6 visits.