Skip to main content

Documentation standards

Two audiences read this site: people, and retrieval systems. A page that is excellent prose but carries no metadata is invisible to the second. A page stuffed with keywords is useless to the first. These rules are the smallest set that serves both.

The frontmatter contract​

Every page carries this block. It is not decoration — it becomes the metadata stored alongside each embedded chunk, and it is what makes filtered retrieval possible ("only customer-facing pages about meetings, reviewed this year").

---
title: Publishing a board pack
description: One sentence a search result can show, written for a reader who has not opened the page.
keywords: [board pack, publish, distribute, agenda]
category: help | developer | governance | security | api | release-notes
product_area: meetings | minutes | voting | actions | passport | seals | pam | billing | admin
audience: customer | internal | both
last_reviewed: 2026-08-04
version: 1.0
---

audience is load-bearing, not advisory. internal pages are filtered out of any customer-facing retrieval. That filter is applied at query time from this field — so a page marked wrongly is a leak, and marking it correctly is the whole control. When in doubt, mark it internal; a customer never suffers from a page they cannot see, whereas the reverse is a disclosure.

last_reviewed is a date someone actually looked, not the date the file changed. Stale documentation is worse than absent documentation because it is believed. A page more than a year past review should be treated as suspect by both a reader and a retriever.

description is written for someone who has not opened the page. It is the search result, the AI snippet, and the social card. "Overview of the board pack feature" tells a reader nothing; "How to assemble, publish and distribute a board pack, and what directors see when you do" tells them whether to click.

Every feature page has three sections​

This is the rule that makes support work. A ticket arrives, and the customer explanation and the engineering context are on the same page rather than in two systems that were last reconciled at some point nobody remembers.

## User guide
What the customer does, in their words. No implementation.

## Technical notes
How it actually works. Tables, routes, gates, jobs, known constraints.
Marked `audience: internal` if it should not be public.

## Support notes
What goes wrong, how to tell, and what to do. Symptoms first — the person
reading this has a symptom, not a diagnosis.

Written symptom-first because that is how a ticket arrives. "Pam stopped answering" is what you are told; "the board exhausted its credits" is what you must work out. A Support Notes section organised by cause makes the reader translate before they can search.

Style​

Australian English. Board vocabulary, not software vocabulary — a "resolution" is not a "record", a "director" is not a "user", and minutes are not "content". Our readers are company secretaries and directors; using their words is a form of respect and it also makes retrieval work, because they search in their vocabulary rather than ours.

Second person for instructions ("Open Settings, then…"). Present tense.

Say what a thing costs and what it cannot do. Documentation that only describes the happy path is marketing. A credit cost, a plan requirement or a known limitation belongs on the page, not in a footnote a support agent has to remember.

Headings​

Sentence case. Descriptive rather than clever — headings are anchors, search results, and the boundaries chunking splits on, so ## Sealing a decision carries meaning where ## Making it official does not.

Never skip a level. Chunking uses heading depth to decide what belongs together, and a jump from ## to #### merges two ideas into one chunk.

Before you commit​

  • The build must pass. Broken links fail the build on purpose — a broken link in documentation is a support ticket that did not need to exist.
  • last_reviewed updated if you actually reviewed the content.
  • audience correct, especially if the page names internal systems, hosts, credentials or customer data.