Most technical writing problems aren't vocabulary problems. They're voice problems. The page reads like a marketing brochure, a research paper, or a note-to-self, when it should read like a colleague explaining the task at your desk. This guide is the shortest path to voice that works for docs.
The four rules
1. Second person — 'you'
"You add the record to your DNS provider." Not "users add", not "one adds", not "the record is added by the user". Second person is direct, unambiguous, and accessible.
2. Active voice
"The parser reads the file." Not "the file is read by the parser." Active voice is shorter, clearer, and keeps the subject front and centre.
3. Imperative for instructions
"Click Save." Not "you can click Save", not "clicking Save will...", not "users should click Save". Tell, don't suggest.
4. Specific over vague
"Sets colors.primary to hex #0ea5e9." Not "sets your brand colour to a nice blue." Docs earn trust by being precise.
The twenty words to avoid
Remove these from your writing. They either add nothing or actively mislead.
| Avoid | Because |
easily, simply, just | If it were easy the reader wouldn't be reading docs. Removing the word doesn't change the meaning; its presence implies the reader is slow. |
please | Begging. Imperative without please is direct; with please is weirdly formal. |
obviously, clearly, of course | If it were obvious you wouldn't document it. These words make readers feel dumb. |
very, really, quite, rather | Intensifiers without specificity. "Very fast" is slower than "under 50ms". |
excellent, awesome, great, powerful | Marketing adjectives in reference content. Reference docs describe, they don't sell. |
leverage, utilize | Say "use". Every time. |
functionality, capabilities | Say "feature" or just name the thing. "The feedback functionality" → "the feedback widget". |
in order to | Say "to". Always shorter, always clearer. |
synergy, solution | Corporate filler. Name the actual thing. |
best practice | Overused. If it's truly a best practice, show the evidence. If not, say "recommended pattern". |
would, could, might | Softens claims unnecessarily. "You might want to set..." → "Set...". Take a position. |
robust, scalable, enterprise-grade | Unverifiable claims. Quantify or skip. |
Quick before-and-after:
❌ "In order to easily leverage the powerful feedback functionality,
simply click the Configure button. You might want to explore
some of the awesome customization options!"
✅ "To configure feedback, click **Configure**. You can customise
prompts, reasons, and the GitHub-issue integration."63 → 24 words. Same meaning. Reads like a colleague.
Heading intent
Each heading announces what the reader will find in the section. Bad headings waste attention.
| Heading intent | Good | Bad |
| Reference | ## Rate limit headers | ## About the headers |
| How-to | ## Add a custom domain | ## Custom domains (is it a how-to? a concept?) |
| Explanation | ## Why we rate-limit per API key, not per IP | ## Rate limiting |
| Troubleshooting | ## Fix: 429 with Retry-After: 3600`` | ## Common issues |
Headings answer the question "what question is this section for?". If you can't answer that, rewrite.
Verb-first headings for how-to
For sections that teach a task, start with a verb.
❌ "Authentication setup"
✅ "Set up authentication"
❌ "Adding a custom domain"
✅ "Add a custom domain"
❌ "Configuration of the AI assistant"
✅ "Configure the AI assistant"The verb-first form matches user queries ("how do I ...") and signals what the reader will DO.
Sentence shape
One idea per sentence
If your sentence has three commas and an "and" in the middle, it's probably two sentences. Split.
Subject near the verb
"The parser, after walking every ref and resolving the composition keywords, builds the schema tree." → "The parser walks refs, resolves composition keywords, and builds the schema tree."
Concrete nouns, concrete numbers
"Takes a while" → "Takes about 5 seconds." "Lots of memory" → "Uses 512 MB peak."
No nested negatives
"It's not uncommon for users not to realize..." → "Users often don't realize..."
Paragraph structure
One idea per paragraph. If you switch topic mid-paragraph, break.
First sentence carries the claim. Subsequent sentences qualify, illustrate, or limit the claim. Not the reverse.
Aim for 40-80 words. Paragraphs over 100 words usually mean two ideas squashed together.
Tone registers for different content types
Reference docs, tutorials, and explanations each want a slightly different register:
Reference
Register: dispassionate, exhaustive, flat.
Voice: third person on the subject, second person on the reader.
Example: "The theme field accepts one of ten slugs. You set it by editing nookdocs.config.json."
How-to
Register: direct, imperative, time-bound. Voice: second person throughout. Example: "Add the CAA record. Wait 60 seconds for DNS propagation. Trigger verification from the dashboard."
Tutorial
Register: encouraging, first-person plural in setup, imperative in steps. Voice: "We'll build X. First, install the SDK." Example: "Let's set up your first Acme integration. Start by installing the package."
Explanation
Register: narrative, opinionated, comparative. Voice: first person plural for product claims; second person for reader engagement. Example: "We built rate-limiting per API key rather than per IP because most of our users sit behind corporate NAT."
See content types for the Diátaxis framework that maps these four modes to distinct page types.
Accessibility notes that affect tone
Write for a screen reader. Imagine the page read aloud by VoiceOver or JAWS. "Click the button" works. "Click the one in the red circle" does not — screen readers don't narrate colour.
Avoid spatial instructions. "Above" and "below" fail in single-column mobile layouts. Use named anchors: "See the Rate limits section."
Expand acronyms on first use. "CAA (Certificate Authority Authorization) record." Subsequent uses can be bare.
Number formats consistently.
1,000not1000or1k— screen readers handle commas better.
Tone patterns that don't work
Edit passes
Write first, edit second. One-pass writing produces voice problems. A three-pass edit catches them:
Shape pass. Does each paragraph have one idea? Does each section have a verb-first heading? Are there dead intro paragraphs?
Voice pass. Any "we" that should be "you"? Any passive that should be active? Any suggestive language that should be imperative?
Density pass. Can each sentence lose 2-3 words without losing meaning? Are there filler adjectives to cut? Can prose become a table or a list?
Aim for 30% shorter on the third pass than the first draft. If you're cutting less, you weren't over-writing.
References
The Microsoft Writing Style Guide — the definitive modern reference, freely available.
Google Developer Documentation Style Guide — complementary, slightly more opinionated.
Related
Writing for LLMs — dual-audience extension of the same foundations
Content types — Diátaxis framework
GEO — AI search optimization — ranking in AI answer boxes
Component library — the primitives that enforce structure