What Technical Writing Is — and Who Does It

Nightjar is a small online service that checks whether websites are up and alerts their owners when one stops responding. Its README opens with: "Nightjar leverages a multi-region synthetic probing paradigm to deliver best-in-class observability." It sounds impressive, yet a new visitor still has no idea what Nightjar does for them. You have just been hired as Nightjar's first technical writer. This course follows you as you fix pages like that one.

The rule

Technical writing helps one kind of reader do one real thing.

Technical writing is writing about a specialised subject, such as software, machines, medicine or finance, for people who need to understand or use it. It is judged by a single measure: after reading, can the reader do what they came to do? Add a monitor, fix an error, choose a plan, pass an audit.

Three habits follow from that measure:

• A reader, not "everyone". A developer connecting to Nightjar's API and a shop owner reading an outage email need different pages.
• An action, not an impression. Writing that impresses but does not help has failed. Plain writing that gets the job done has succeeded.
• Accuracy first. A graceful sentence with a wrong command does more harm than a clumsy one with the right command.

A technical writer is the person whose job is to do this well. The core skill is translation: learning from experts such as engineers, scientists and product managers, then rebuilding that knowledge in the order and the words a reader needs. The writer is rarely the person who knows most about the product. They are the person who knows most about what the reader needs from it. Plenty of engineers, support agents and teachers write technical content part of the time; a technical writer does it on purpose, with a process and a craft.

Here is the README line rebuilt for its reader:

Nightjar checks your website every few minutes and emails you when it stops responding.

Same product. Now the reader knows what it does for them.

The shortcut

Before you judge or write any piece, ask two questions: Who is reading? What will they be able to do afterwards? If the text does not answer both, it is not finished.

The common mistake is writing to prove how much you know. The shortcut catches it: knowledge the reader cannot act on is noise on that page.

Drills

Answer fast — trust the rule.

Remember

• Technical writing helps one kind of reader do one real thing.
• Shortcut: ask "Who is reading?" and "What will they be able to do afterwards?"
• Trap: writing to show what you know instead of what the reader needs.