| name | technical-writing-policy |
| description | Concise, realistic technical copy - UI microcopy, labels, descriptions, setting hints, empty/error states, and README/doc prose that informs without over-explaining, restating the obvious, or leaking implementation detail. Use whenever writing or reviewing user-facing text: a dashboard/app label or description, a settings hint, a panel intro, a button, a skill/package description, a README section, or any doc copy. Also use when the user complains that descriptions are too long, over-explained, obvious, or "cutre". |
Technical Writing Policy (Concise, Realistic Copy)
User-facing text is design material, not decoration. Every word must earn its place.
Give the reader exactly what they need to act - not less, not more. This policy owns
descriptive copy: labels, descriptions, hints, empty/error states, panel intros, and
README/doc prose. Commit/PR prose is owned by git-policy; visual design by frontend-design.
Core Principle
A description says, in plain terms, WHAT a thing is or does and why the reader should
care - from the reader's side of the screen. It is not a tutorial, not a changelog, not
a spec, and not a place to show your work.
The test for every sentence: would removing it lose information the reader needs to act
or decide? If not, cut it. If you can't remember a button's exact label, it's good
microcopy - the reader shouldn't have to study it.
The Cardinal Sins (cut these)
- Narrating the obvious. Do not describe the controls the reader can already see.
"Edit a skill's content, disable/enable or remove it" next to Edit/Disable/Remove
buttons tells the reader nothing - they can see the buttons. Describe the thing, not
the toolbar around it.
- Leaking implementation detail. The reader does not need the internals. A password
form does not say "hashed with SHA-256"; a sync feature does not list its diff
algorithm. Surface mechanism only when the reader must act on it (a security warning, a
destructive-action caveat, a real constraint they hit).
- Redundant cross-references and meta-commentary. "...the same as the terminal UI",
"as mentioned above", "this section explains..." - filler that orients nothing. State
the thing directly.
- Hedging and marketing. "powerful", "simply", "just", "seamless", "robust", "in
order to". Plain verbs and concrete nouns instead.
- Restating the heading. A panel titled "Accounts" whose intro begins "Manage your
accounts" wastes the first line. Add information the title does not already carry.
- Over-explaining a feature. A feature card or list item sells the outcome in one or
two lines, then stops. Cut the mechanism, config internals, every flag, and the edge
cases out of the pitch - lead with what the reader gets, name the command or show the
one example that proves it, and leave the rest for the docs. A landing/README feature
list whose job is to make the reader want it still obeys this: punchy beats thorough.
Three padded sentences hide the hook that one tight sentence would land.
Rules
- Name things by what the reader controls and recognizes, not by how the system is built
(a person manages notifications, not webhook config).
- Be specific over clever: "Resets Monday 11:00" beats "Resets soon".
- Match length to the slot: a setting hint is one line; a panel/page intro is one sentence
of orientation plus, only if needed, one of consequence (a caveat, a default, a cost).
An empty state is one line that invites the next action. A feature card leads with the
benefit in the first clause, runs one or two sentences, and lets the command or example
carry the proof - never a how-it-works paragraph.
- Active voice, present tense, sentence case. The control names the exact action ("Save
changes", not "Submit"); the same verb survives the whole flow (Publish -> "Published").
- Errors say what went wrong and how to fix it, in the interface's voice - never vague,
never an apology, never a raw stack trace or internal error to the user.
- Be realistic, not aspirational: describe what it actually does today, not the roadmap.
- READMEs: assume a competent reader. Explain what is non-obvious or load-bearing (how to
run it, the one surprising constraint, why a choice was made) and skip what the audience
already knows or can infer from the code. Lead with the point; cut the throat-clearing.
Reviewing existing copy
When asked to fix "bad"/over-explained descriptions: read each line and delete what fails
the test above. Prefer one tight sentence over three padded ones. Keep every load-bearing
fact (a real constraint, a default, a cost, a security caveat); cut everything that only
restates the obvious or narrates the UI. Report what you cut and why in one line.
Boundaries
- Respond in the user's language; copy itself is written in the project's language
(English here) per core-engineering-policy.
- Commit messages and PR text: git-policy. Visual/typographic design: frontend-design.
Validation/error-handling logic: validation-policy. This policy governs the words.
