Skip to main content

Writing a page

Engineers and agents write these pages in the same pull request as the code they describe. Product, support and QA read the rendered site.

Where things go​

  • Area → module → feature page. Never nest a fourth level. If a page grows too big, split it into sibling pages.
  • One folder per module. It holds the module's index.md (the Overview), its feature pages and its .feature specs.
  • Folder and file names are the page title in kebab-case, using the app's own wording.
  • Each folder has a _category_.json with its sidebar label and position.

Voice​

  • Describe what people see and do, in plain language and the app's own words: menu labels, status labels and role labels.
  • Say "a bank payment shows Processing for a few business days, then Paid", not which job or webhook updates it.
  • Never name Lambdas, webhooks, database fields or functions. Where an internal name is unavoidable, define it in the Glossary.
  • Mark anything not yet checked against the code with (verify).

Module overview​

A module's index.md covers: a one-paragraph summary, who uses it, its lifecycle at a glance, an In this section table of its feature pages, where it shows up, and permissions.

Feature page template​

Every feature page uses these sections, in this order. Leave out a section that doesn't apply to the feature.

  1. Title and summary: what the feature is, in one plain paragraph.
  2. Who uses it: supplier staff and restaurants, and what each one does.
  3. How it works: the flow as people experience it, including timings.
  4. Calculations: each rule with a worked example using real numbers, a table where it helps, and a callout for the reason behind a surprising rule.
  5. Where it shows up: app screens, PDFs, emails, pay pages, checkout text, reports.
  6. Permissions: who can see it and who can change it.
  7. Decisions: a one-line decision, a one-line reason, and a link to the issue or PR.
  8. Specs: link each sibling .feature file on a line of its own. The site renders it in place.
  9. Known limitations
  10. FAQ: the questions a confused supplier or support person actually asks, in their own words. Give a short, direct answer that links to the rule. Use it wherever the feature can be confusing.

Front matter​

Readers never see it. CI's stale-docs check and the QA bot read it.

KeyHolds
codeGlobs of the source files the page describes
modulesAPI modules involved
surfacesWhere it shows up: screens, PDFs, emails, links, reports
specsNames of the .feature files that test it, no extension
ownerGitHub handle of the person who keeps the page up to date

Skeleton​

---
title: Due date & payment terms
sidebar_position: 2
code: [packages/api/src/modules/sale-order/service/transition-rules.ts]
modules: [sale-order]
surfaces: [invoice-pdf, invoice-email, invoice-list]
specs: [due-date-and-terms]
owner: github-handle
---

# Due date & payment terms

One paragraph: what it is, in plain words.

## Who uses it

## How it works

## Calculations

:::info[Why this rule]
The reason behind a surprising rule.
:::

## Where it shows up

## Permissions

## Decisions

- **Decision in one line.** Reason in one line. (#1234)

## Specs

[due-date-and-terms.feature](./due-date-and-terms.feature)

## Known limitations

## FAQ

**The question, as a supplier would ask it?**
A short, direct answer that links to the rule.

Specs​

  • Specs are Gherkin .feature files, written in user and business language. /spec-plan writes them and /spec-check audits them.
  • Each file starts with a # prefix: XXX comment. Every scenario has an ID with that prefix, such as Scenario: IMM-006 …, and no two scenarios anywhere share an ID.
  • A test that covers a scenario carries a // @spec IMM-006 comment above its it().