Contributing and maintaining

Documentation is part of the service experience. Update it when user-visible behavior, an operator procedure, an integration, a route, a data contract, or a service’s lifecycle changes.

Before you write

1. Identify the question the page must answer.
2. Check the service’s source repository for current behavior.
3. Search these docs for an existing canonical page. Update it instead of creating a competing explanation.
4. Read the repository’s .github/WORK_TRACKING.md before creating or closing planned work.

Choose the right page type

• Write a tutorial for a guided first experience.
• Write a how-to for an operational goal or troubleshooting procedure.
• Write an explanation for architecture, behavior, and tradeoffs.
• Write reference for exact APIs, routes, configuration, and data.
• Use a dated design document for a proposed or point-in-time change.
• Use a dated announcement for an audience-friendly shipped change.

Do not combine every page type into one giant document. A service landing page should orient the reader and link to the deeper layer.

Page metadata

Every Markdown page requires title, description, type, and status. The description should be one plain-language sentence that helps someone decide whether the page answers their question. It also improves search results and link previews.

A complete frontmatter block looks like:

---
title: Clear human-readable title
description: One sentence used by search engines and link previews.
type: service-doc
status: active
---

Use lifecycle status consistently:

Status	Use it when the page describes…
active	Current behavior or a service in use
approved	An accepted design that may not be built yet
decommissioned	A service or workflow that has been retired
dev	Work in development or testing
legacy	Superseded behavior kept for historical reference
planned	A proposal that has not been built
shipped	A completed, point-in-time design or announcement

Use the narrowest existing type that matches nearby pages.

Service landing pages should also state:

• the service purpose and current lifecycle state;
• its public and protected surfaces;
• its runtime, storage, and trust boundaries;
• links to architecture, operations, and reference;
• the live site and source repository when applicable.

Writing standard

• Lead with the fact, behavior, or question the page resolves.
• Use short, familiar words and direct sentences.
• State what is true now before history or plans.
• Cut throat-clearing such as “this section provides,” “at a glance,” and “in order to.”
• Avoid sales language such as “seamless,” “robust,” “powerful,” and “comprehensive.”
• Do not call routine behavior “intelligent,” “innovative,” or “AI-powered.” Name the model-assisted step and its review boundary when that fact matters.
• Do not repeat the audience, purpose, and status in both a callout and the opening paragraph.
• Introduce acronyms and product names in plain language before relying on them.
• Put commands, routes, fields, and configuration names in code formatting.
• Give screenshots meaningful alternative text that explains what matters.
• Distinguish public URLs from protected admin URLs.
• Mark destructive, email-sending, live-display, or production-changing steps before the reader reaches them.
• Include prerequisites, verification, and rollback when a procedure changes live state.
• Link to the canonical page instead of copying details that can drift.
• Write link text that names its destination; avoid “click here” and raw URLs in prose.
• Use exact dates for lifecycle statements such as migrations and retirements.

Choose the lightest useful visual

Every visual should do a specific job that prose cannot do as quickly.

• Use a screenshot to show an interface, layout, or state the reader needs to recognize. Crop to the relevant area, use a current public or sanitized view, and write alternative text that explains what matters.
• Use a diagram when three or more parts, decisions, or steps interact. Keep labels plain and let the surrounding text explain the consequence rather than repeating every box.
• Use a table for exact mappings or comparisons readers may scan more than once.
• Use prose or a short list for a single fact, a simple decision, or a small sequence.

Name screenshot files by service and subject. Add a date when the interface is likely to change, and replace the image when a material UI change makes it misleading. Never add a screenshot only as decoration.

For editorial patterns, start with GitHub Docs’ content design principles, its style guide and content model, and the UK Department for Education’s plain-language guidance.

Privacy and security boundary

Never publish:

• secret values, tokens, cookies, or recovery codes;
• resident names, email addresses, votes, submissions, or other private records;
• private infrastructure addresses or account identifiers;
• unsanitized production logs or screenshots;
• instructions that bypass required access controls.

Examples should use obviously fictional values. Screenshots must be reviewed for personal data, browser chrome, notifications, and hidden metadata before they are committed.

Local review

From the repository root:

npm run docs:setup
npm run docs:dev

Review the page at desktop and mobile widths. Check that its title, table of contents, links, tables, callouts, diagrams, and images are understandable.

Before opening a pull request:

npm test

The check creates the production Quartz site and validates frontmatter, local images, alternative text, Mermaid rendering, private-address safety, and generated page and section links.

Review checklist

• A reader can identify the page’s scope and current state from the opening paragraph.
• The page has one clear purpose and uses the appropriate document type.
• Current behavior is separated from planned, legacy, or historical behavior.
• Operational actions include prerequisites and a way to verify success.
• Technical claims point to a source file, contract, or authoritative external reference where useful.
• No private or secret material is present.
• npm test passes.

When a service is decommissioned, update its service landing page, the service directory, and the system overview in the same change. Keep historical pages only when they remain useful, and label them clearly.