Community OS Documentation Standard

This standard is the single reference for every user-facing document in Community OS. It defines the three doc types, the guide template, the plain-language rules, the accessibility rules, and the frontmatter schema. Follow it for every new document and every edit to an existing one.

The templates are ready to copy: see the guide, concept, and reference templates in the _template folder.

Doc types

Every document has exactly one doc type. The type is set in the frontmatter docType key.

Guides

A guide helps a reader complete one task. It follows the 8-section template and nothing else. Put the task in the title, as a verb phrase, such as "Delegate authority" or "Review and revoke consent".

Write the steps for one person and one task. Do not cover every option in the instructions. Put rare options in the troubleshooting section.

Concepts

A concept answers "What is ...?" in plain language. It has four parts: a definition, when you use it, an example using the Community OS personas, and related terms. Link to the guides that put the concept into practice. Do not restate the guides.

Reference

A reference is for lookup, not for reading start to finish. Use tables with a header row. Keep each row short. Put the most-looked-up facts first. The glossary and this standard are references.

Technical

A technical doc is deliberately brief. It names one underlying technology, explains it in plain language, tells the reader why it matters, and links to the engineering document that describes it in full. It does not duplicate the engineering content. The reader is a user or administrator who wants to understand how the system works, not an engineer who wants to build on it.

The 8-section guide template

Every guide has the same eight H2 sections, in this order. Use the exact section titles.

1. Purpose — one or two sentences about the task the guide helps with. Answer "what will the reader be able to do".
2. Who this is for — the reader's role, from the audience list. If more than one role can do the task, say so.
3. What you need — everything the reader must have before starting. Be specific, such as "your email address" or "the trustee's identity (DID)".
4. What you will do — a short numbered overview of the whole task, no more than five or six steps.
5. Instructions — the numbered steps. One action per step. Follow the plain-language rules in this standard.
6. What happens next — what the reader should expect after the task, including status text where relevant.
7. Troubleshooting — the common problems and their fixes, in a list or table.
8. Related guides — a list of links to the guides and concepts the reader is most likely to need next.

Plain-language rules

These rules follow ISO 24495-1.

• Use short sentences. One idea per sentence.
• Use the active voice. "You grant consent" not "Consent is granted by you".
• Use "you" for the reader. Use the persona names (Wiremu, Hana, James, Aroha) for the other people in examples.
• Define every term the first time you use it. Link the first use of a controlled term to the glossary.
• One action per instruction step. Do not combine actions: "Set the start date." and "Set the end date." are two steps.
• Use the imperative mood in instructions. "Select Grant consent."
• Write positive instructions first, then negative ones. "Choose Sign in." before "Do not close the window."
• Keep instructions free of legal and technical jargon. If you must use a technical term, define it in plain language on first use.
• Use numerals for numbers in instructions. "for 15 minutes" is fine in prose; steps prefer digits.
• Make lists real lists. Use - for unordered and 1. for ordered. Never fake a list with dashes in a paragraph.

Accessibility rules

These rules follow WCAG 2.2 and the needs of screen-reader users.

• Content must be readable in a linear order. Do not structure a document so the reader must jump back and forth.
• Use semantic headings. The site renders the frontmatter title as the page's H1, so the body must not contain an H1. Start the body with ## sections, then ### subsections. Do not skip levels.
• Make every heading descriptive. A heading must tell the reader what follows, not "More" or "Details".
• Use real tables with a header row for tabular data. Do not use tables for layout.
• Make link text descriptive. The link text must name the destination: "Read the guide to grant consent", not "click here" or "read more".
• Always show status as text: "Status: Active". Never rely on colour alone. Colour may support text, but the text must stand alone.
• Never give directions based on position or appearance: no "above", "below", "left", "right", "see the diagram", "the green button".
• Name controls by what they do: "Select Delegate authority". Do not say "the button on the right".
• When a document includes an image, the caption or surrounding text must state what the image shows. If the image carries no information, say the image is decorative. Do not write "see the image".
• Keep the reading level simple. Short paragraphs. Short sentences.

Frontmatter schema

Every user document starts with a YAML frontmatter block. The keys are fixed and must appear in this exact order.

---
title: <plain title>
slug: <kebab-case unique slug>
docType: guide|concept|reference|technical
domain: trust-network|getting-started|...
audience: [trustee, beneficiary, support-worker, coordinator, family, admin]
summary: <one plain-language sentence>
related: [<slugs of related docs>]
order: <int for nav ordering>
updated: 2026-08-25
---

Validation rules:

• title — a plain title, one line, no trailing period.
• slug — lower-case, kebab-case, unique across all user docs. Used in URLs and in related links.
• docType — one of guide, concept, reference, technical. User docs use guide, concept, or reference; technical is for the brief technology explainers that link to the repo docs/ files.
• domain — the product area the document belongs to, such as trust-network or getting-started.
• audience — a YAML list of roles drawn from the controlled set: trustee, beneficiary, support-worker, coordinator, family, admin. At least one entry.
• summary — exactly one plain-language sentence.
• related — a YAML list of slugs of other user docs. Use [] if none.
• order — an integer used for navigation ordering. Lower numbers come first.
• updated — the last-review date in YYYY-MM-DD form. Update it whenever you change the document.

Terminology and controlled vocabulary

Use the controlled vocabulary. Definitions live in the glossary. When you use a controlled term for the first time in a document, link it to the glossary.

Two rules are fixed and must appear wherever relevant:

• Consent is never implied by a delegation or an arrangement. Third-party access always needs both the relationship and an active consent.
• Record-scoped access is denied for unknown, deleted, or out-of-date records with a 403 status. The guides describe this to users as "you cannot open the record".

Related

• Glossary