Voice and Writers
| Field | Value |
|---|---|
| Type | Skill Resource |
| Source | ~/.copilot/skills/technical-writing/references/voice-and-writers.md |
| Description | Not specified |
Source Content
Voice and Writers
The taste anchor for this skill: whose voice to channel for each document type, the journalist’s tools that keep a doc honest and complete, and the register for readers who don’t share your technical context. Pair it with personas.md for who appears in the writing; this file is about who stands behind it.
Writer models
One entry per writer. The “channel when” line names the doc type that wants their voice.
The clarity school
William Zinsser
Strip every sentence to its cleanest components — clutter is the disease of writing. His warmth matters as much as his scissors: the doc should sound like a person who cares whether you follow. Channel when: every doc, every draft.
Strunk & White
Omit needless words. Their rule is mechanical and merciless, which makes it perfect for the editing pass — read each sentence and ask what survives deletion. Channel when: the 20% cut, after the draft exists.
Richard Feynman
If you can’t explain it simply, you don’t understand it yet. He rebuilt hard ideas from everyday parts — start from what the reader already knows, and treat failure to explain as your gap, not theirs. Channel when: explanations for non-technical readers.
The structure school
Daniele Procida
Mixing the four kinds of documentation is the root of most bad docs. His Diátaxis framework makes mode the first decision — tutorial, how-to, reference, or explanation, never two at once. Channel when: choosing the mode, before any words.
John McPhee
Structure is decided before drafting — he diagrams a piece before writing a line. For a long doc, the outline is the argument; if the spine doesn’t hold, no sentence will save it. Channel when: any doc over two pages; migration guides; discovery docs.
Mark Baker
Every page is page one. Readers arrive mid-document from search, so every section must orient them and link out to what it depends on. Channel when: troubleshooting guides, FAQs, reference pages.
The reader-empathy school
Julia Evans
Friendly curiosity, small drawings, and open delight in not knowing yet. Her zines prove a hard topic can stay rigorous while sounding like a friend explaining it — “not knowing is fine” is a stance, not an apology. Channel when: explainers, tutorials, anything for learners.
Kathy Sierra
Make the user awesome. The doc upgrades the reader; it does not describe the product — every section should leave them able to do something new. Channel when: tutorials, how-tos, READMEs.
Ann Handley
Audience empathy plus the “so what?” test — every paragraph must answer what it changes for the reader. She writes marketing that respects people, which is exactly the register an announcement needs. Channel when: announcements, blog posts, release notes.
Don Norman
It’s not your fault the door is confusing. Design (and write) for how people actually behave — blame the doc, never the reader, and fix the doc. Channel when: error messages, troubleshooting, onboarding.
The docs-as-craft school
Tom Johnson
Documentation is a product, not a deliverable. Iterate on real usage — I’d Rather Be Writing tracks API docs and AI-assisted workflows as living things. Channel when: maintaining a doc set over time.
Anne Gentle
Treat docs like code. Git, review, CI, and Markdown keep docs current — a doc without a pipeline is already rotting. Channel when: setting up doc tooling and gates.
The journalist’s kit
Three tools from the newsroom that keep any doc honest, complete, and front-loaded.
The inverted pyramid (BLUF)
Bottom line up front: the lede carries the whole point — claim and consequence — and each layer below adds detail for whoever keeps reading. An executive who reads only the first two sentences still leaves with the decision. Never bury the ask in the third section. Use in: status updates, announcements, incident comms, any exec-facing doc.
The 5W1H completeness check
Who, what, when, where, why, how — run the list before shipping. A how-to missing when (the trigger) or a status update missing who (the owner) fails silently for the reader. It takes thirty seconds and catches the gap you’re too close to see. Use in: every doc, as a final pass.
Question craft for extracting material from SMEs
How-tos and runbooks come out of someone’s head. Getting them out is interviewing, and the full method lives in question-craft.md — this kit is the working summary:
- Open-ended prompts — “walk me through the last time this broke” beats “does it break often?”.
- Follow-ups that dig — “what surprised you?”, “what did you check first?”, “what would a new person get wrong?”.
- Silence as a tool — the Didion move: after their answer, wait. The second answer is usually the real one.
Writing for non-technical readers
The director-to-stakeholder register. The reader is smart, busy, and not fluent in your stack — write to their decision, not your implementation.
- BLUF, always. State the outcome and the ask in the first two sentences. Detail is for those who keep reading.
- No unexplained jargon. Define every term on first use, or cut it. “The cache” needs no gloss; “cache stampede” does.
- Analogies before mechanisms. Give the picture first (“a queue outside a club”), the mechanism second — and only if they need it.
- Numbers in context. “2× last month” beats “12,438 requests”; every figure gets a comparison, a trend, or a threshold.
- What-this-means-for-you framing. End each section with the consequence for the reader: what changes, what they must decide, what happens if nothing is done.
Jack and Jill still open the doc — see personas.md. Just write the scene in non-technical terms: a missed deadline, not a missed test; a customer complaint, not a stack trace.
For the other half of natural voice — never writing as if the prompter, not the reader, is the audience — see natural-voice.md.