Writing conventions

Page status (`status` in frontmatter)

Value	Meaning
`stub`	Skeleton only, no content yet
`draft`	Being written, or summarised from a BRD not yet approved
`reviewed`	A second person (Dev/Tester/another BA) has reviewed it
`approved`	Matches a BRD approved by the customer

Function page frontmatter

---
title: "Repair / Rework"
description: "One sentence on what the function does."
module: MES                       # MES | WMS | …
status: draft
flow: mes/repair-rework           # slug on the flow site
brd: "FC_BRD_RepairRework_v0.2_20261013.docx"   # BRD used as basis; empty if none
owner: "FC project BA"            # responsible role, not a personal name
---

Codes

Kind	Form	Example
Business rule	`BR-<FUNCTION CODE>-nn`	`BR-RW-05`
Functional requirement	`FR-<CODE>-nn`	`FR-RW-04`
Acceptance scenario	`AC-nn` (within the page)	`AC-06`
Open question	`OQ-<CODE>-nn`	`OQ-RW-03`
User decision	`Q-YYYYMMDD-nn` (from the Q&A log)	`Q-20261013-01`

The function code comes from the BRD (Repair / Rework = RW). With no BRD yet, the BA sets one and writes it on the page.
Never renumber or reuse an existing code. To drop a rule, keep the row, strike it and give the reason: ~~BR-RW-04 …~~ (dropped 20/10/2026, Q-…). Dev and Tester have cited the codes in code and test cases; renumbering breaks traceability.
A BR-… code is defined on one page only. The checker reports duplicates as errors.

Cite sources, separate observation from inference

Every Dev/Test note that says something about the system must state where and when it was seen:

Kind	How to write it
Observation	“On DEV (10.0.68.230:3011), 13/10/2026: clicking Save with Qty = 0 shows no error.”
From documents	“Per BRD v0.2 section 6.5 …”
Inference	“Inferred from … — not confirmed by anyone.”

Don’t mix observation and inference in one sentence.
Numbers carry their denominator and source: “9/2,351 rows, DEV query 07/10/2026”, not “very few”.

Quote verbatim

Copy field labels, button names and error messages exactly as on screen, in backticks, even when misspelt. Don’t tidy them — if something looks wrong, add a row to Open questions.

When this page and the BRD disagree

The BRD is the official basis until the BA updates it. Don’t quietly change a rule in the base to match the code — add a question to section 10 and tell the BA.

Terms

Use the exact words in the Glossary. For example on WMS screens the production order is labelled Work Instruction, never Production Order.