Mostly harmless, conspicuously useful

The Hitchhiker's Guide to Becoming a Technical Writer

A technical writer produces the documentation that no one reads and everyone needs, which is a perfectly reasonable arrangement until the on-call engineer opens the runbook at three in the morning and finds that the screenshot is from a version of the product that has been retired, the example calls an API that has changed, and the step numbered four now refers to a button that has been renamed, moved, or sentenced to deletion. You learn to translate "the system does a thing" into plain, precise, audience-appropriate language that a reader can follow at the speed of an emergency, and to structure that language so the answer is findable before the reader has finished formulating the question. Documentation is now treated as code, which means it can break the build like any other code, be reviewed like any other code, and drift from the product like any other code that no one has touched since the last reorganisation. This guide travels from editing one awkward paragraph to setting content strategy for a documentation organisation, with practical stops at information design, API reference, docs-as-code, editing, and the recurring discovery that a doc marked "current" is merely current to the date of the last person who looked. The grand objective is documentation that helps users succeed; the daily evidence is usually a sentence that a reader can follow, an example that actually runs, and a page whose screenshot fails to surprise anyone except the engineer who shipped the change, who has learned not to be surprised by their lack of surprise.

Things to recognise

• A page marked "current" is current to the last review date, not to the product; docs drift silently because the product changes without notifying the page, and a screenshot is usually wrong before the prose is.
• Style guides list preferred terms, capitalisations, and structures, while actual consistency depends on a reviewer, a check, or a build that fails on deviation; a guide without enforcement is a wish with a table of contents.
• Confirm the product version, the screenshot date, and the example's runtime before publishing, because a correct sentence for the wrong version is still impressively misleading and surprisingly persistent.

Take the useful exit

Level 1 · Novice

Read the doc before the screenshot ages into archaeology

You inspect existing docs, style guides, change notes, and screenshots without publishing, learning how a perfectly polite page can mislead a reader for years after its product has moved on.

You begin with read-only artifacts: published docs, a style guide, a glossary, recent release notes, screenshots, code examples, and a changelog that has not been updated since a reorganisation. Technical writing is explaining complex systems in plain, precise, audience-appropriate language, while editing is reviewing content for accuracy, consistency, and style compliance. You review these with engineers, support staff, and an experienced writer so that everyone can trace how a feature becomes a sentence a reader can follow before anyone publishes a page whose example calls an endpoint that no longer exists.

Suppose a support rep reports that the install guide "doesn't work." In a read-only review, you open the page, follow each step against a current build, and find that the screenshot shows a button labelled "Connect" that is now labelled "Sign in," that the install command references a package version two majors old, and that step four refers to a dialog that has been removed. You record the discrepancies and the date each was last correct. One brisk audit is an anecdote with good posture, not a rewrite; but it prevents the team from publishing a tutorial for a product that has not existed in the form shown for two release cycles.

Words from the spaceship manual, translated

Style guide: A shared set of rules for voice, tone, terminology, formatting, and structure that documentation follows. It turns "write clearly" into a set of decisions a team can apply consistently, and a style guide no one enforces is a leaflet.
Release notes: A dated record of what changed in a release, written for the audience that has to live with the change. They are how a reader learns what is new, what is gone, and what now behaves differently, and they are the document most likely to be drafted by an engineer in a hurry.
Screenshot: A picture of the product at a moment in time, useful immediately and misleading forever after. It is the documentation element that ages fastest, and a screenshot that has not been reviewed in a year is a historical reenactment.
Code example: A snippet a reader is expected to copy, run, and adapt. An example that does not run is a sentence with better typography, and an example that runs against a different version than the reader has is a confidence reduction exercise.