> Language and editorial guide for agent-written copy — from The Handover, the-handover.org/docs/language-editorial-guide > Authors: Leon Mallett (captivated.online) with Claude Code · Last confirmed working: 2026-08-15 > © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence How this product writes. Applies to interface copy, error messages, documentation, release notes and anything else a person reads. ## The failure this prevents An agent writes plausible product prose at scale. Each piece reads acceptably; the problem is that each was written from scratch. So the same concept acquires four names. A button says "Delete", a dialog says "Remove", a toast says "Discarded" and the docs say "Archive" — for one action. Nothing is wrong enough to flag in review, and the product starts feeling like several products built by people who never met. **Inconsistent terminology costs more than any individual bad sentence**, because a reader who has learned a word expects it to keep meaning the same thing. When it stops, they stop trusting that they have understood anything. ## Voice and tone **Voice is constant. Tone varies with the situation.** The voice: plain, precise, and confident without being pleased with itself. Explain rather than announce. Assume the reader is capable and busy. The tone shifts with what the reader is doing: - **Routine actions** — brief, almost invisible. Get out of the way. - **Something went wrong** — calm and specific. No apology theatre, no jokes. Someone is already frustrated. - **Destructive confirmations** — direct and unambiguous. Say exactly what will be lost. This is not the place for reassurance. - **Empty states and onboarding** — warmer, because there is room to be, and a person deciding whether to continue. ## Mechanics - **Spelling: {{spelling_variant}}.** Applies to prose and interface copy. Code identifiers, API fields and third-party names keep their own spelling — `color` stays `color` in CSS. - **Headings: {{heading_case}}.** Applied everywhere, including buttons, labels and table headers. - **Serial comma** where it removes ambiguity; not as a rule to enforce everywhere. - **Numbers:** words for one to nine in prose, numerals from ten; numerals everywhere in interface copy, where scanning matters more than flow. - **Dates:** unambiguous and never numeric-only. "14 August 2026", not "14/08/2026", which means something else in half the world. - **No exclamation marks** in interface copy. If the sentence needs one to carry its enthusiasm, the sentence is the problem. ## Terminology is a list, not a preference Keep the product's own vocabulary written down: the word used for each concept, and the words deliberately not used for it. - **One concept, one word, everywhere** — interface, documentation, error messages, support replies, marketing. - **Record the rejected synonyms too.** "We say *project*, not *workspace*, *board* or *space*" is more useful than the preferred term alone, because it is the rejected ones that turn up in new copy. - **Prefer the user's word to the internal one.** If the codebase calls it a `Tenant` and users call it an organisation, the interface says organisation. - **When introducing a new concept, name it once and deliberately**, then use that name. A name that emerges accidentally across three features is a name nobody chose. ## Error messages The most-read and least-written copy in any product. A good one answers three questions: 1. **What happened** — specifically, in the user's terms. 2. **Why**, if knowing helps. 3. **What to do now** — the part most often missing. Rules: - **Never blame the user.** "That email address is already registered" rather than "You entered an invalid email". - **Never expose internals.** Stack traces, table names, status codes and exception classes are for logs. If a reference is needed for support, give a short opaque identifier. - **Never say "an error occurred".** It is the only sentence guaranteed to be true and useless. - **Match severity to reality.** Not everything is an error — much of what gets styled as one is information, or a state. - **Make recovery reachable from the message itself**, rather than describing a path the reader has to navigate. ## Microcopy - **Buttons are verbs** describing what happens: "Save changes", "Delete project". Never "OK" on a destructive action, where the reader is confirming something they should have read. - **Labels are nouns.** Help text goes under the field, not in a placeholder — placeholder text disappears exactly when it is needed. - **Links describe their destination.** "Click here" and bare URLs fail for anyone scanning or using a screen reader, both of whom read links out of context. - **Say what will happen before it happens**, particularly for anything irreversible, anything costing money, and anything other people will see. ## Words to avoid - **"Simply", "just", "obviously", "easy".** If it were, nobody would be reading this sentence. They make a stuck reader feel stupid. - **"Please" in interface copy.** It is filler in most places and reads as pleading in the rest. - **Anthropomorphising the software.** It did not "think" or "want". It did something, or failed to. - **Apologising repeatedly.** Once, if warranted, then fix it. - **Hedging in documentation.** "Should work" means nobody checked. ## The boundary with the design system This document owns **the words**: what they say, in what voice, using which terms. The **container and its behaviour** — how a control looks, its states, its spacing — belongs to the design system. Where they meet, the design system sets the constraint and this sets the style: it says a button label must fit on one line at the narrowest width; this says a button label is a verb. If the words will not fit the container, that is a conversation, not a licence to abbreviate into something unclear. ## What needs a human - **Anything published under the product's name** — release notes, announcements, public pages, support replies. - **Renaming a concept.** That is a terminology change affecting every surface, not a copy edit. - **Legal, privacy or compliance wording**, which is not editorial text even when it reads like it. - **The first copy for a new concept**, which sets the term everything else inherits. Draft any of these. Do not publish them.