Docs copywriting
Write every human-facing page as a developer sharing what they know with a peer: plainly, warmly, and in words people say out loud. Never as a company presenting, and never as a system talking to itself.
Core principles
Sentence case for all titles. Write "Running a session", never "Running A Session".
Plain speech, no AI dialect. Words agents use with each other do not survive into human docs. See the translation table below.
Problem before solution. Show the reader the situation they recognize before naming what solves it.
Specific over vague. "Under a minute" beats "quickly". "Seven commands" beats "a set of commands".
Define terms on first meeting. The docs may teach a term of art — orchestrator, shaping, lane — but the first time a reader meets it, a plain-words definition sits right beside it.
Never boast. The work speaks; the copy never points at it. No claims about our results, no case studies, no benchmarks, no showcase.
Peer tone. Write like you are explaining to a friend over coffee — a fellow developer, not an audience.
AI dialect translation table
Words from the workflow's internal dialect that never appear in human docs:
| Dialect |
Write instead |
| load-bearing |
essential, "that everything depends on" |
| binding |
required, "the rule is" |
| doctrine |
standing instructions, the rules |
| surface (as a noun) |
page, screen, place |
| charter |
instructions, the task |
| invoke |
run, type, use |
| adjudicate |
decide, rule on |
| materialize |
create, generate |
| canonical |
official, "the one source" |
| affordance |
button, link, control |
| artifact |
file, document, result |
| downstream / upstream |
later / earlier |
| ergonomics |
how it feels to use |
| corpus |
the reference library (the books and posts the method draws on) |
When a dialect word carries a concept the docs genuinely need, keep the concept and teach it under a plain name with a first-use definition — never smuggle the word.
Literal identifiers are the one exception: command names, configuration keys, and exported symbols are written exactly as they are — seasoned-skills corpus, webSurface — and the concepts they carry get plain names in prose (the reference library, the web checks).
Quick reference
| Element |
Pattern |
Example |
| Headlines |
Sentence case, plain topic or problem |
"Running a session", "When the context fills up" |
| Rhythm |
Short declarative + longer explanation |
"It is one command. The package generates everything your agents read, and none of it enters your history." |
| Em dashes |
Spaces around them, one or two per page |
"The person — not the agent — decides when to compact." |
| Technical terms |
Concept first, brief plain definition beside it |
"compaction (summarizing the session so far to free space)" |
| Unsettled practice |
Described honestly, marked as evolving |
"Today we ship through GitHub releases; the staging story is still settling." |
Anti-patterns (never do these)
- Title Case headlines
- Em dashes without spaces, or more than two on a page
- Corporate jargon: leverage, utilize, seamless, robust, best-in-class, cutting-edge, empower, optimize, synergy, solution
- AI dialect from the table above
- Claims about our results or the quality of what the workflow produces
- Passive voice where a person acts: "The context can be compacted" → "Compact the context"
- Hedging: "should probably", "may want to consider"
- Teaching a direction as if it were settled practice
- Over-explaining what a working developer already knows
Detailed guidance
For the full voice reference with examples, see references/voice-guide.md.
1---2name: docs-copywriting-23description: Write human-facing prose for this repository in our voice — the README, every page under docs/, and any other copy a person reads. Use when writing or editing documentation, GitHub-facing text, or prose in release notes meant for human readers.4---56# Docs copywriting78Write every human-facing page as a developer sharing what they know with a peer: plainly, warmly, and in words people say out loud. Never as a company presenting, and never as a system talking to itself.910## Core principles11121. **Sentence case for all titles.** Write "Running a session", never "Running A Session".13142. **Plain speech, no AI dialect.** Words agents use with each other do not survive into human docs. See the translation table below.15163. **Problem before solution.** Show the reader the situation they recognize before naming what solves it.17184. **Specific over vague.** "Under a minute" beats "quickly". "Seven commands" beats "a set of commands".19205. **Define terms on first meeting.** The docs may teach a term of art — orchestrator, shaping, lane — but the first time a reader meets it, a plain-words definition sits right beside it.21226. **Never boast.** The work speaks; the copy never points at it. No claims about our results, no case studies, no benchmarks, no showcase.23247. **Peer tone.** Write like you are explaining to a friend over coffee — a fellow developer, not an audience.2526## AI dialect translation table2728Words from the workflow's internal dialect that never appear in human docs:2930| Dialect | Write instead |31|---------|---------------|32| load-bearing | essential, "that everything depends on" |33| binding | required, "the rule is" |34| doctrine | standing instructions, the rules |35| surface (as a noun) | page, screen, place |36| charter | instructions, the task |37| invoke | run, type, use |38| adjudicate | decide, rule on |39| materialize | create, generate |40| canonical | official, "the one source" |41| affordance | button, link, control |42| artifact | file, document, result |43| downstream / upstream | later / earlier |44| ergonomics | how it feels to use |45| corpus | the reference library (the books and posts the method draws on) |4647When a dialect word carries a concept the docs genuinely need, keep the concept and teach it under a plain name with a first-use definition — never smuggle the word.4849Literal identifiers are the one exception: command names, configuration keys, and exported symbols are written exactly as they are — `seasoned-skills corpus`, `webSurface` — and the concepts they carry get plain names in prose (the reference library, the web checks).5051## Quick reference5253| Element | Pattern | Example |54|---------|---------|---------|55| Headlines | Sentence case, plain topic or problem | "Running a session", "When the context fills up" |56| Rhythm | Short declarative + longer explanation | "It is one command. The package generates everything your agents read, and none of it enters your history." |57| Em dashes | Spaces around them, one or two per page | "The person — not the agent — decides when to compact." |58| Technical terms | Concept first, brief plain definition beside it | "compaction (summarizing the session so far to free space)" |59| Unsettled practice | Described honestly, marked as evolving | "Today we ship through GitHub releases; the staging story is still settling." |6061## Anti-patterns (never do these)6263- Title Case headlines64- Em dashes without spaces, or more than two on a page65- Corporate jargon: leverage, utilize, seamless, robust, best-in-class, cutting-edge, empower, optimize, synergy, solution66- AI dialect from the table above67- Claims about our results or the quality of what the workflow produces68- Passive voice where a person acts: "The context can be compacted" → "Compact the context"69- Hedging: "should probably", "may want to consider"70- Teaching a direction as if it were settled practice71- Over-explaining what a working developer already knows7273## Detailed guidance7475For the full voice reference with examples, see [references/voice-guide.md](references/voice-guide.md).
seasonedcc