Language and editorial guide for agent-written copy

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.