Module Docs Structure Convention

Single source of truth for how every product module's docs are structured. The mirror skeleton lives at content/{en,vi}/modules/_template/ (excluded from the published site — copy from source). Every module — core, extended, or industry — follows this exact shape.

This is the product/business counterpart to the engineer-facing Developer Docs Structure. Module docs describe what the product does for users; developer package docs describe how it is built.

1. Goals

Goal	Why it matters
Uniformity	A reader who knows one module's docs knows them all. No discovery cost.
Audience-fit	Written for PM / PO / BA / QE / sales — business language, not implementation detail.
Spec ↔ test traceability	Every requirement (URD) maps to a test case (TC) by ID. Nothing untested, nothing untraced.
End-to-end linkage	A reader can follow one feature from roadmap → module → PRD → ADR → dev → test → runbook in a few clicks.
Visual-first	Tables + mermaid (graph, stateDiagram-v2, sequenceDiagram, erDiagram) over prose.
Status-honest	Each module/feature declares Built / In-progress / Planned so readers never mistake a roadmap item for a shipped feature.
Code-as-truth	Built features describe actual behavior verified against the codebase, not aspirations.

2. Module Tiers

Tier	Folder	Meaning	Phase
Core	modules/core/	Essential, every merchant needs it	A
Extended	modules/extended/	Growth/engagement add-ons	B
Industry	modules/industry/	Vertical-specific solution bundles	C
Use Cases	modules/use-cases/	End-to-end scenarios that compose multiple modules	—

Industry solutions are compositions of core/extended modules, not new modules. Their pages reference the modules they bundle rather than re-specifying them.

3. Folder Layout

content/{en,vi}/modules/<tier>/<module>/
├── index.md          # ⓜ Identity card: purpose, scope, capabilities, dependencies, key flows
├── urd.md            # ⓜ User Requirement Doc: personas, scope, functional requirements, acceptance
├── test-cases.md     # ⓜ (Built/In-progress) Test cases traceable to URD IDs
├── prds/
│   ├── index.md      # ⓜ PRD catalogue
│   └── YYYY-MM-DD-<slug>.md   # ⊕ one PRD per feature increment
└── <feature>.md ...  # ⊕ Optional per-feature deep dive (rarely needed at module level)

ⓜ mandatory · ⊕ optional

Folder-based, like developer packages. The overview lives at <module>/index.md so the URL stays /modules/<tier>/<module>. Do not keep a sibling <module>.md file.

Status-scaled mandatory set

Module status	Mandatory files
Built / In-progress	index.md + urd.md + test-cases.md + prds/index.md
Planned (not yet built)	index.md + urd.md (stub OK) + prds/index.md — test-cases.md optional until build starts

4. Document Roles

Page	Role	Answers
index.md	Identity card / overview	"What is this module, what can it do, what does it depend on?"
urd.md	User Requirement Doc	"What must it do for users, and how do we know it's correct?"
prds/*.md	Product Requirement Doc	"What are we building this increment, and why?"
test-cases.md	Verification	"How is each requirement proven?"
<feature>.md	Feature deep-dive	"How does this one non-trivial sub-area behave end to end?"

Rule: keep roles separate. Requirements live in URD; rationale/increment scope lives in PRDs; proof lives in test-cases. The overview links to all three and duplicates none.

5. Per-Page Templates

Skeleton files live at content/{en,vi}/modules/_template/ (source only). Section order is fixed.

index.md — 10 sections

Traceability block (see §6.1) · Identity (table) · Purpose & Scope (in/out) · Capabilities · Module Dependencies · Backend Packages (link to developer docs) · Key User Flows (mermaid) · Roles & Permissions · Status & Roadmap · Related Pages

urd.md — 9 sections

Header (module id · version · date) · Purpose · Scope (in/out) · Definitions · Conceptual Model (mermaid) · Functional Requirements (ID + MoSCoW priority tables) · Acceptance Criteria (Given/When/Then) · Constraints & Non-Goals · Version History

test-cases.md — 3 sections

Coverage Summary (count per requirement group) · Test Cases (one table: TC ID · URD ref · Scenario · Steps · Expected · Priority) · Traceability (URD → TC matrix; flag any uncovered requirement)

prds/index.md

Single table: PRD · Date · Status · Title · Modules touched.

prds/YYYY-MM-DD-<slug>.md — PRD

Context (problem/opportunity) · Goals & Non-Goals · Requirements (link URD IDs) · UX / Flows · Rollout & Metrics · Open Questions.

6. ID & Traceability Conventions

Artifact	ID format	Example
Module	<TIER>-NN	CORE-06, EXT-02, IND-03
URD requirement	URD-<AREA>-NNN	URD-STK-001
Test case	TC-<AREA>-NNN	TC-STK-001
PRD	PRD-<AREA>-NNN	PRD-STK-001
ADR (dev)	ADR-NNNN	ADR-0005
Priority (requirements)	MoSCoW: Must · Should · Could · Won't	—

• <AREA> is a short 2–4 letter code per functional area, consistent across URD, TC, and PRD so they line up (URD-STK-001 ↔ TC-STK-001).
• IDs are zero-padded, sequential, and never reused — even after a requirement is dropped, its number is retired, not recycled.
• Every Must requirement has at least one test case. The test-cases.md Traceability section must flag any gap.

6.1 Traceability block (top of every module index.md) — MANDATORY

The wiki has ONE spine: a reader must be able to follow a single feature from roadmap → module → PRD → ADR → dev → test → runbook. Every module index.md opens with this fixed block. Missing links are written — (never omitted) so gaps are visible:

> **Status:** In-progress · **Owner:** <name> · **Phase:** 1 · **Last reviewed:** YYYY-MM-DD
>
> | Chain | Link |
> |-------|------|
> | Roadmap | [Phase 1](/en/delivery/roadmap#phase-1) |
> | PRD | [PRD-STK-001](./prds/2026-05-10-opening-balance) |
> | URD | [URD](./urd) |
> | Decisions (ADR) | [ADR-0001](/en/developer/packages/inventory/decisions/0001-polymorphic-inventory-item) |
> | Dev docs | [@nx/inventory](/en/developer/packages/inventory/) |
> | Tests | [Test Cases](./test-cases) |
> | Runbook | [Inventory ops](/en/runbook/operations/) |
> | Delivery log | [Traceability matrix](/en/delivery/traceability-matrix) |

6.2 Reciprocal "Related Pages" footer — MANDATORY

Markdown links are one-directional, so a link MUST be added in BOTH directions. When you add module → ADR, also add ADR → module. Every page ends with ## Related Pages. Required reciprocal pairs:

If page A links to B	B must link back to A
module index → developer package	package index → module
module index → roadmap phase	roadmap phase row → module
PRD → URD requirement IDs	URD → its PRDs
URD ↔ test-cases	test-cases ↔ URD
module / PRD → ADR	ADR "Related" → module / PRD
feature → runbook	runbook → feature / package

A lightweight CI lint can later verify every related: reference resolves and is reciprocated — the cheap stand-in for build-time link checking.

7. Authoring Style Rules

Rule	Enforcement
Audience	PM/PO/BA/QE/sales. Explain features in user terms; link to developer docs for internals — never inline schema/SQL/code.
Visual-first	Tables/mermaid for any list ≥3 items. Prose only when neither fits.
Compact prose	Max 4 lines per paragraph. Bullet > paragraph.
Frontmatter	Always title, description, outline: deep.
Status badges	Use VitePress <Badge> for phase/status (Built, In-progress, Planned, Phase A/B/C).
Cross-link	Internal links use /en/... absolute path. Link module → backend package docs, and module → use-cases that use it.
English-only in identifiers	Vietnamese only in user-facing localized strings.
No emojis	Unless part of a UI being documented.

8. Status & Roadmap Policy

Status	Meaning	In index.md
Built	Shipped and verifiable in code today	Describe actual behavior
In-progress	Partially shipped	Mark which capabilities are live vs pending
Planned	Roadmap only	Clearly labelled; no claims of working behavior

Roadmap phases (P1/P2/P3 within a module, and tier Phase A/B/C) live in the Status & Roadmap section of index.md and link to the delivery roadmap. Do not scatter phase notes through requirement tables — keep them in one place.

9. EN ↔ VI Parallel

Rule	Detail
Mirror	Every EN file has a VI counterpart at the same relative path
Line parity	EN/VI line counts within ±5%
Translation order	EN ships first → VI follows in batch
Mermaid labels	Translate node labels; keep state/event identifiers and IDs in English
Frontmatter title & description	Translated
IDs / code / identifier names	Never translated (URD-STK-001, CORE-06, entity names)
Link graph	Traceability-block and Related-footer links are identical across EN/VI — translate prose, never diverge the link graph. EN is canonical for IDs.

10. Sidebar Convention

Each module nests under its tier. A module with sub-pages shows them in fixed order:

<Module Name>            (link → index.md)
├─ URD
├─ Test Cases
├─ PRDs                  (link → prds/index.md)
└─ <feature pages…>      (only if any)

Rules:

• Module label links to index.md; sub-items follow in order URD → Test Cases → PRDs → Features.
• A Planned module with only an overview shows as a flat link (no nested items).
• Industry solutions are flat links (they compose, not specify).

11. Bootstrapping a New Module

# 1. Copy skeleton
cp -r content/en/modules/_template content/en/modules/<tier>/<module>
cp -r content/vi/modules/_template content/vi/modules/<tier>/<module>

# 2. Replace placeholders: <Module Name>, <TIER>-NN, <AREA>, TODO:, dates
#    Fill the §6.1 traceability block (use — for links that do not exist yet)

# 3. Register in sidebar: .vitepress/locales/en.ts and vi.ts

Step	Owner
Copy skeleton + fill index.md (incl. traceability block) + urd.md	PM/PO/BA
Add test-cases.md when build starts	QE
Add a PRD per increment	PM/PO
Sidebar registration	Author

12. Anti-patterns (do not do)

Anti-pattern	Why bad
Sibling <module>.md + <module>/ folder	Two homes for one module; use <module>/index.md
module-<x>-urd.md / module-<x>-tc.md long names	Redundant prefix; use urd.md / test-cases.md
Inlining DB schema, SQL, or code in module docs	Wrong audience; link to developer package docs
Requirements with no test case	Breaks traceability; every Must needs a TC
Mixing requirements, rationale, and proof on one page	Use URD / PRD / test-cases respectively
Describing Planned features as if Built	Misleads readers; always status-badge
One-directional links	Breaks the spine; add the reciprocal Related link (§6.2)
Omitting the traceability block	A reader cannot follow the feature end-to-end
Free-form per-module structure	The whole reason this convention exists

13. Related

• Developer Docs Structure — engineer-facing counterpart
• Delivery — Roadmap — forward-looking phase plan
• Delivery — Traceability Matrix — cross-project coverage view
• _template/ skeleton — content/{en,vi}/modules/_template/
• Modules Overview — the module catalog
• MoSCoW prioritization — https://en.wikipedia.org/wiki/MoSCoW_method