Command First, Explanation Second

#resources #resources/writing #resources/programming

Command first, explanation second

The voice rules for software docs are tighter than the voice rules for articles. Articles can wander; docs can't.

Second person, imperative

"Press b." Not "the user may press b." Not "one presses b." The reader is the protagonist. The doc is talking to them.

This rules out a lot of academic phrasing that creeps in when authors are uncomfortable being direct. "It is recommended that…" becomes "Run…". "Users typically…" becomes "Use…". Shorter, more concrete, no hedging.

Show before tell

The command comes before the explanation, not after. The reader scans for code blocks; if the code shows up first, the reader can paste it and read the prose afterward to understand what they just ran.

This inverts the academic instinct ("first I'll explain, then I'll demonstrate"). For docs, the demonstration leads.

No "click here" or "see above"

Link text names the destination: [CLI overview](/reference/cli/), never click [here](/reference/cli/). "See above" is worse than worthless — it forces the reader to scroll without telling them what they're scrolling for.

Placeholders paired with real values

--to alice@example.com is fine. --to YOUR_EMAIL on its own is not. The reader needs a concrete shape to imitate. Use real-looking placeholder addresses consistently (alice@example.com, bob@example.com) — and pair them with the abstract pattern when the abstraction matters.

Inline code for code things

File paths, directory names, function names, flags, config keys, command names — all inline code. Prose drift around technical terms is the fastest way to make a doc feel sloppy.

How this differs from article voice

Article writing wants rhetorical questions, anecdotes, contrasts, parentheticals. See My Writing Style Guide for that style. Docs want none of it. The reader didn't come for prose; they came for a procedure. Save the voice for explanation pages, where reasoning is the point.