Natural Voice
| Field | Value |
|---|---|
| Type | Skill Resource |
| Source | ~/.copilot/skills/technical-writing/references/natural-voice.md |
| Description | Not specified |
Source Content
Natural Voice
Two failure modes make a document sound machine-written. Both are easy to check for, and both are covered here.
The audience is the reader, never the prompter
Someone asked for this document. Someone else — often a stranger — will read it. Those are two different people, and the document is never for the first one.
A prompt-writer might say “add a rollback section” or “make this shorter.” That instruction shapes the document, but it never appears in the document. Not as a thank-you, not as a summary of what changed, not as a note about why a section exists.
Sounds like a robot addressing the prompter
- “Here’s the document you requested.”
- “I’ve created this guide to help you understand X.”
- “As you asked, this covers the rollback steps.”
- “Note: I added this section based on your feedback.”
- “I hope this guide helps!”
- “As an AI, I can’t guarantee this covers every case.”
Sounds like a document
- Opens with the two-person story or the lede — never a summary of the request.
- States what it covers because the reader needs to know, not because someone asked for it to be added.
- Never mentions its own creation, its author’s confidence, or the conversation that produced it.
Read the draft and ask: could the actual reader tell an AI wrote this for someone else? If a sentence only makes sense to the person who typed the prompt, cut it.
Say the role, not “human”
“Human” describes a species, not a job. It shows up in machine-written prose exactly where a person would have named the role instead — the tell is unmistakable.
Name the specific role when you have one. Fall back to “people” or “someone” when you don’t.
| Robotic | Natural |
|---|---|
| ”a paged human at 3 a.m." | "a paged engineer at 3 a.m." |
| "the human who responds to the alert" | "the on-call engineer" |
| "written for humans" | "written for people" |
| "a human traces those" | "an engineer traces those" |
| "the human judgment" | "the reviewer’s judgment" |
| "human-visible state changes" | "user-visible state changes" |
| "the human connection" | "the personal connection” |
Two exceptions, both narrow:
- A direct quote. Never edit a real person’s words to remove “human” — that misquotes the source. Attribute it and move on.
- A real title. How Complex Systems Fail, The Field Guide to Understanding Human Error — cite it exactly as published.
Everywhere else, if a sentence would sound normal coming from a person talking about their own team, “human” doesn’t belong in it. People don’t call each other “humans” in conversation. A document that reads like one person explaining something to another shouldn’t either.
The check
Before shipping, reread the opening and closing paragraphs specifically for these two tells. They cluster at the start — summarizing the request — and at the end, thanking the reader or hoping it helped.
scripts/voice_lint.py catches the most common phrasings automatically. It runs advisory, alongside the other lints in lints.toml.