Technology Expertise — Understand Before You Explain
Nightjar's quick start says: install the command-line tool, then run nightjar monitors add with your site's address. You follow it on a fresh laptop and get Error: not logged in. Nobody on the team had noticed, because their own machines had been logged in for months. You caught it for one reason: you actually ran the steps.
The rule
Use it before you explain it; test every step yourself.
How technical does a technical writer need to be? Not enough to build the product. Enough to:
- use it as the reader will: install it, configure it, and break it on purpose to see the errors;
- read and run the samples: commands, configuration files and API requests;
- follow the big picture: which parts talk to which, at the level of a simple diagram;
- ask engineers precise questions that can be answered in a sentence.
Here is the quick start as it should read, and as you proved it works:
nightjar login
nightjar monitors add https://shop.example.com --interval 5m
nightjar monitors listMost writers build this expertise on the job, one product at a time. A few basics pay off almost everywhere in software documentation: the command line, how web requests and responses work, the JSON data format, and Git.
Precise questions matter because engineers are busy. Compare "Can you explain monitors?" with "If a Free-plan user sets --interval 1m, does the command fail or quietly use five minutes?" The second takes thirty seconds to answer, and the answer goes straight into the docs.
The shortcut
Do it, then write it. Start from the same blank state as a new reader, follow the draft word for word, and treat every surprise as either a fix or a question.
Start clean
A new account, no saved login, a fresh terminal: the state a brand-new reader is in.
The trap is writing from the specification or an engineer's description alone. A spec says what the team intended. Only the product shows what it actually does, and when the two disagree, the reader meets the product.
Drills
Answer fast — trust the rule.
Why did Nightjar's engineers miss the missing login step?
Which question to an engineer is most useful?
How much technical depth does a technical writer need?
The spec says the default check interval is 5 minutes, but your test monitor checks every 10. What do you do?
Remember
- Use it before you explain it; test every step yourself.
- Shortcut: do it, then write it, starting from a clean state and following the words literally.
- Trap: writing from the spec alone, which describes intent rather than behaviour.