technical-writing-policy

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)

1. 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.
2. 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).
3. 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.
4. Hedging and marketing. "powerful", "simply", "just", "seamless", "robust", "in order to". Plain verbs and concrete nouns instead.
5. 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.
6. 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.