Skip to main content
Everyone

House style

Every page here follows one shape, so the manual reads as one document rather than a hundred. This page is that shape.

Voice​

  • Second person, present tense, imperative. "Select Add Connector." Not "the user should click".
  • "Select", never "click". Everything in the product is keyboard-reachable, and a reader on a keyboard or a screen reader is not clicking.
  • UI labels verbatim and in bold. Engagement Status, not "the engagement field". The authoritative list of shipped strings is the tenant UI's own translation catalogue — if a label is not there, it is not shipped text, so do not write it.
  • British English. Organisation, recognise, licence.
  • Say what a thing does, not what it is called. Readers arrive mid-task.

Length — brief, not thin​

250–400 words of body text per task page. Cover every decision the reader has to make and every state they can get stuck in. Cut history, design rationale, and any point already made once.

The test for a sentence: does it change what the reader does next? If not, delete it. A reader who is stuck is not reading for pleasure.

Structure​

A task page, in this order and with no extra sections:

  1. Lead — one or two sentences. What this page gets you.
  2. <PermissionNote> — the module, the exact permission, and what must already exist.
  3. ## Steps — one <HowTo> with 3–6 steps. Each names its UI label in bold.
  4. ## What success looks like — two or three observable signals: a badge value, a message, where a row appears.
  5. Optional: one short section for a genuine gotcha the steps cannot carry.
  6. ## If something goes wrong — a Symptom / Likely cause / What to do table, 3–5 rows.
  7. ## Next — two or three internal links.

Reference pages — status tables, glossaries, this page — are exempt. They have no steps.

One task per page. If you are past six steps, it is two pages.

Rules the build enforces​

These fail the build, not the review:

  • title unique and ≤ 60 characters. description unique and 50–160 characters, written as a real sentence.
  • Exactly one H1 — the title renders it, so the body uses ## and never skips a level.
  • Every <Figure> has non-empty alt, and its id matches a committed master.
  • Every internal link resolves. Every page is reachable from the sidebar.
  • lastVerified on any page with steps, and draft_stub: true on any page not yet written.

Verify, don't paraphrase​

Steps are written against the running product, not against a design document. Design docs describe intent; the manual describes behaviour. Where they disagree, the product wins — and the page records which build it was checked against in verifiedAgainst.

Next​

Steps verified on . Something wrong with this page?