Skip to main content

Copy

Voice​

  • British English in sentence case, written in full sentences in a calm, specific, human voice. Write for any employee, not just engineers: someone in finance or support should understand every label and message.
  • Explain in everyday words first and keep the technical term for where it helps ("Who can see this data", not "ACL"). When a technical word is the right one (SQL, schema, MRN), use it without apology.
  • The product term is "catalog".
  • Say what happened and what to do next. Nothing else.
  • No em dashes, hype verbs ("Supercharge", "Unlock", "Seamless"), staccato fragments or grouping in threes for rhythm.

Words​

  • Use the plain, common word over an idiom: "manually" not "by hand", "automatically" not "on its own", "remove" not "get rid of".
  • Labels use the same words as the sentences around them: "Manual" and "From rules", not "Added by hand" and "Dynamic".
  • One name per thing, everywhere: a data product is never also a "bundle" or a "collection".

Buttons and labels​

  • Buttons are a verb plus an object ("Run query", "Add plugin", "Delete asset"). No "→" on buttons.
  • Labels and headers are sentence case. A heading does not need a description when it already says it.
  • Destructive actions say what they destroy ("Delete data product", not "Delete").

Numbers and live data​

  • Never write sentences that summarise live data, such as "One pipeline failed overnight and 37 queries were refused." The app has to count, pluralise and translate every combination, and the sentence goes stale the moment a number changes. Headings and descriptions stay static; numbers live in the components made for them (KPI tiles, counts, status pills, lists).
  • A KPI tile's context line is fixed text too ("Last 30 days", "Refused by policy before running"), never "27 of 30 runs succeeded". A second number gets its own tile or field.
  • Do not spell out counts that a shape already shows. A folded object or list shows a brace and a preview of what is inside, not "6 keys" or "1 item"; screen readers still hear the count.
  • Prefer a visual to a figure when the exact value does not change what someone does. Popularity is four bars, not "Top 9%" or "988 views"; keep exact numbers for things people act on or compare.
  • Do not repeat state. "23 results" is enough; never echo the whole query or the applied filters back in the count.
  • Numerals for counts (3 owners, not three owners).

Cut​

  • Filler: figure captions, "for example" notes, lines that narrate what the screen shows, helper text that restates the label or explains the obvious ("Click to open").
  • More than one short sentence of description under a heading.
  • Badges for the happy path. "Succeeded", "Allowed" and "Active" are the default and need no pill.
  • Product versions, builds and hostnames on any screen a signed-out person can reach.

Empty states and errors​

  • Empty states say what is missing and what to do about it: "No assets have been catalogued from this source yet. Add a plugin to catalogue it."
  • Errors say what failed, why if known, and the next step: "The run failed after 412 ms because the credentials expired. Update them in Plugins."
  • Content a plugin or an agent generated carries a small "Plugin" or "Generated" tag, never a sparkle.