Forms of Technical Writing
In your first week at Nightjar you are asked for four things: a clearer error message for bad URLs, steps for the engineer on call at 3 a.m., details of the /v1/monitors endpoint, and a note telling customers about SMS alerts. All four are technical writing. None of them looks like the others.
The rule
Match the form to the reader and the moment they are in.
Technical writing is not one kind of document. It takes many forms, and each exists because a particular reader, at a particular moment, needs a particular shape of help:
| Form | Main reader | Their moment | Nightjar example |
|---|---|---|---|
| Help articles and user guides | Product users | Doing a task, or stuck | "Set up email alerts" |
| Developer docs and API reference | Developers | Building an integration | The POST /v1/monitors page |
| Interface text | Anyone using the product | Mid-task, on screen | The message under the URL field |
| Internal docs and runbooks | Colleagues | Working, often under pressure | "When every check from one region fails" |
| Release notes | Existing users | Something just changed | "New: SMS alerts on the Team plan" |
| Technical marketing | People evaluating the product | Deciding whether to adopt it | A tutorial or white paper |
Outside software there are more: equipment manuals, safety instructions, standard operating procedures in factories and labs, and regulatory documents in fields such as medicine and aviation. The principle is the same. The reader's situation decides the form.
Forms also differ in how they are read. A reference page is looked up, so it must be easy to scan and exact. A runbook is followed under stress, so it needs short numbered steps. Interface text is glanced at, so it has a few words to do its job.
The shortcut
Ask "Who, and when?" Name the reader and the moment they meet the content. The form follows.
"Customers keep pasting bad URLs"
Who: a user in the middle of adding a monitor. When: right now, on screen. Form: an error message beside the field, not a help article they would never open.
The trap is using one familiar form for every need, such as answering everything with a long blog post or a giant FAQ. The content may be correct and still arrive in the wrong shape at the wrong moment.
Drills
Answer fast — trust the rule.
A user has just typed an invalid URL into the add-monitor form. Which form helps them most?
An on-call engineer needs exact steps for when every check from one region fails. Which form fits?
Who is the main reader of an API reference, and how do they use it?
Which statement about technical writing is accurate?
Remember
- Match the form to the reader and the moment they are in.
- Shortcut: ask "Who, and when?" and let the form follow.
- Trap: forcing every need into one familiar form, such as a long post or a giant FAQ.