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.
The Feature Spine
The whole wiki has one spine, and the unit that ties it together is the Feature.
A Feature is a Functional Area - the existing
<AREA>code (STK,PO,BOM…). We do not invent a new ID system: a feature's requirements (URD-<AREA>-NNN), increments (PRD-<AREA>-NNN), and tests (TC-<AREA>-NNN) are already keyed to it. We simply name the thing those codes point at and make it first-class.
A feature lives in two homes with two jobs, joined by one Feature ID (<module>/<AREA>):
| Home | Job | Audience |
|---|---|---|
| Delivery (feature catalog) | The list - name · status, grouped by Phase → Epic. No business detail. | PM / managers |
URD (urd.md) | The description - what each feature does for users, its requirements and acceptance. This is the business documentation. | PM / PO / BA / QE |
Delivery Phase → Epic → Feature (list + status, link → URD) [PM view - simple]
URD Feature = one entry: business description + requirements + acceptance
PRD a build increment of a Feature (1 Feature → many PRDs over time)
Test Case written FROM a PRD (this is when a TC becomes meaningful)
─────────────────────────────────────────────────────────────────────────────────
Module ⇄ Package (horizontal mapping: business ⇄ engineering)One-directional spine: Phase → Epic → Feature (URD) → PRD → Test Case. One horizontal axis: Module ⇄ Package (see the mapping table in §5). Every other rule below serves this spine.
Execution mapping (Plane)
The same spine drives execution. Plane's three tiers map to it, and the Feature is the mandatory anchor for daily work:
| Plane tier | Spine unit | Title | Parent | Mandatory |
|---|---|---|---|---|
| Epic | Epic (E1-E12) | [EPIC/<MODULE>] outcome | - | optional - cross-cutting work (Platform, cross-module Reports) need not belong to an epic |
| Work Item | Feature | [FEAT/<MODULE>] feature name | its Epic, if any | one per Feature |
| Sub-issue | Task (the team's daily work) | [<area>/target] … | a Feature in the current Phase | yes - every task picks a Feature |
Both Epic and Feature titles are prefixed by the capability module (a governed vocabulary), never a free AREA code. The feature's canonical spine ID <module>/<AREA> lives in its URD link inside the work item - the AREA keys requirements and tests (URD-PCK-001), while the title stays human ([FEAT/Sale] Product Picker). A Feature work item carries full labels (Type Feature · Phase · Module) and has no cycle - it is a container. A task is never parented straight to an Epic and never floats free: it always sets parent = the [FEAT/<MODULE>] it advances, so progress rolls up per feature. Epic membership is inherited through that Feature's parent.
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>/
├── urd.md # ⓜ The module's front page - User Requirement Doc: personas, scope, functional requirements, acceptance
├── 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
No per-module hub
index.mdpage.urd.mdis the front page: the module label in the sidebar links straight to the URD. The shared overview of all modules lives at Modules Overview (module table + Module Map). Do not keep a sibling<module>.mdfile.
4. Document Roles
| Page | Role | Answers |
|---|---|---|
urd.md | Front page + User Requirement Doc | "What does this module do for users, and how do we know it's correct?" |
prds/*.md | Product Requirement Doc | "What are we building this increment, and why?" |
<feature>.md | Feature deep-dive | "How does this one non-trivial sub-area behave end to end?" |
5. Per-Page Templates
Skeleton files live at
content/{en,vi}/modules/_template/(source only). Section order is fixed.
5.1 Engineering Mapping (Module ⇄ Package) - the horizontal axis
The horizontal axis lives right in the URD: each feature's header line declares its Dev package (**Dev:** [@nx/inventory](...)), and ADRs are linked from the PRD/package docs. Reciprocal: each linked package index adds a row back to the module (see §6.2).
urd.md - feature-organized
The URD is the module's feature list. Order is fixed:
Header (module id · version · date) · Purpose · Scope (in/out) · Definitions (optional) · Conceptual Model (mermaid, optional) · Feature Catalog (the at-a-glance feature table) · Features (one sub-section per feature) · Constraints & Non-Goals · Version History
- Feature Catalog - a summary table:
Feature ID · Feature · Phase · Status · Priority. This is the scannable feature list; status is per-feature. - Features - the body. One sub-section per feature, in catalog order. Each feature keeps description + requirements + acceptance together so a reader jumps to one feature and sees everything:
### `STK` - Stock Tracking <Badge text="Built" />
**Feature ID:** `inventory/STK` · **Phase:** P1 · **PRDs:** [PRD-STK-001](./prds/...) · **Dev:** [@nx/inventory](...)
What it does for users: <1-3 lines, business language>
**Requirements**
| ID | P | Requirement |
|---|:-:|---|
| URD-STK-001 | **M** | ... |
**Acceptance**
::: details AC-STK-01: ...
| Given | When | Then |
:::The old split - one global Functional-Requirements table plus a separate global Acceptance-Criteria section - is retired. Requirements and acceptance now live inside their feature.
prds/index.md
Single table: PRD · Date · Status · Title · Modules touched.
prds/YYYY-MM-DD-<slug>.md - PRD
Header declares its Feature ID (<module>/<AREA>) so 1 Feature → many PRDs is visible. Body: 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 |
| Feature (= Functional Area) | <module>/<AREA> | inventory/STK, inventory/PO |
| URD requirement | URD-<AREA>-NNN | URD-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 = one feature, consistent across URD, TC, and PRD so they line up (URD-STK-001↔TC-STK-001) and resolve to the same Feature ID<module>/<AREA>.- IDs are zero-padded, sequential, and never reused - even after a requirement is dropped, its number is retired, not recycled.
6.1 Traceability chain - MANDATORY
The wiki has ONE spine: a reader must be able to follow a single feature from roadmap → module → PRD → ADR → dev → test → runbook. The chain lives in two places:
- Each feature's header line in
urd.md-**Feature ID** · **Phase** · **PRDs** · **Dev**(see the §5 template). Missing links are written-(never omitted) so gaps are visible. - Traceability Matrix - the cross-project coverage view per module.
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 |
|---|---|
| Delivery feature row → URD feature anchor | URD feature → Delivery feature catalog |
URD feature **Dev:** line → developer package | package index → module (URD) |
| module URD → roadmap phase | roadmap phase row → module (URD) |
| PRD → URD requirement IDs | URD → its PRDs |
| 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 urd.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 |
Definition of Done - the three gates
Status is not a feeling and not a closed ticket. A feature advances through three explicit gates:
| Gate | Done when | Owner | Signal |
|---|---|---|---|
| Technical completion | code merged + reviewed | Engineer | Plane sub-issue = Done |
| Feature completion | the feature's Must requirements pass their Acceptance Criteria (URD) | PO / QE | Feature work item = Done · wiki badge → Built |
| Release acceptance | the epic's end-to-end Done signal verified on a live merchant | PM | Epic at 100% + verified |
The Plane percentage is a progress indicator only. A feature is Built solely when its Acceptance Criteria pass - not when its tasks close.
Roadmap phases (P1/P2/P3 within a module, and tier Phase A/B/C) live in the
Feature Catalogofurd.mdand 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 → urd.md)
├─ URD (the feature list)
├─ PRDs (link → prds/index.md)
├─ Test Cases
└─ <feature pages…> (only if any)Rules:
- The module label links straight to
urd.md(the front page); sub-items follow the spine order URD → PRDs → Test Cases → Features (a test case is written from a PRD, so PRDs precede Test Cases). - A
Plannedmodule with only a URD 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 (urd.md + prds/)
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 chain in each feature header (use - for links that do not exist yet)
# 3. Register in sidebar (module label points to …/<module>/urd): .vitepress/locales/en.ts and vi.ts| Step | Owner |
|---|---|
Copy skeleton + fill urd.md (incl. per-feature traceability chain) | PM/PO/BA |
| 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 a <module>/ folder with urd.md as the front page |
Re-adding a per-module hub index.md | The hub is retired; the URD is the front page, the shared overview lives at Modules Overview |
| 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 |
| One global Functional-Requirements table + separate global Acceptance section | Retired; organize the URD by feature (§5) so each feature is self-contained |
| A feature in the URD but not in the Delivery catalog (or vice-versa) | Breaks the spine; the two homes must agree |
| 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 chain in URD feature headers | A reader cannot follow the feature end-to-end |
| Free-form per-module structure | The whole reason this convention exists |
13. Related
- Development Lifecycle - the order these artifacts are produced (URD → PRD → ADR → Plan → code → test) and the one home for each
- Developer Docs Structure - engineer-facing counterpart
- Delivery - Roadmap - forward-looking phase plan
- Delivery - Feature Catalog - the per-phase feature list (one home of the Feature Spine)
- 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