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.
  • Write it the way you would explain the product to a colleague. Plain sentences of varied length. Leave out stock phrasing such as "simply", "seamlessly", "it's worth noting" and "in order to".
  • No em or en dashes. Use a comma, a colon, parentheses or a new sentence instead. A spaced hyphen is a last resort, and number ranges take a plain hyphen: 3-6 steps. If a product message contains a dash, paraphrase it rather than quote it.
  • Permission names as Module · Feature - Verb, for example IntELIEDocs · Document - Execute, in prose and in <PermissionNote> alike. Staff pages are the exception: the staff console prints raw keys such as billing.plan.read, so staff pages use the key as the reader will see it.

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 on 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, such as a badge value, a message or 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, because they have no steps.

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

Building blocks​

The site's look follows GitBook's own documentation: a calm reading column, flat cards and tinted hints. Use the blocks below for what they are for, and nothing else.

  • <HowTo> steps. Each step's name is shown as its title, so write it as a short imperative a reader can scan down: "Open the document", "Save". The text underneath carries the detail.
  • Hints. :::note is neutral background, :::info is the one thing to know before you start, :::tip is a shortcut or a better way, :::warning is something that loses work or surprises the reader, and :::danger is something that cannot be undone. Give a hint a title when its point fits in a few words, as in :::warning[Deleting is immediate]. One or two per page at most; a page of hints has no hints.
  • <Cards> / <Card>. Landing pages only: the home page and a module's overview. Each card is one link with a title and one sentence. Never use cards inside a task page; use ## Next links there.
  • <Figure>. See the Figure contract.
  • <FlowDiagram>. For a lifecycle a reader has to see whole, such as a document's statuses, where a list in order hides the branches and the loops. It draws boxes and arrows from positions the page gives it, in the product's status colours, and keeps a prose description for screen readers. Keep the page's table as well: the diagram shows the route, the table says what each status means.

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.
  • A hint's title goes in brackets, :::info[Title]. Written as :::info Title, the whole hint prints as plain text, colons and all.
  • 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, as the product's repository and commit: 'elie-tenant-ui @ 2b9501cf'. A version number is not enough, because the product's version has stayed the same across months of changes.

Next​

Last updated on Something wrong with this page?