The product reference
The canonical cross-module view of a product — actors, concepts, module ownership, journeys and unresolved questions in one stable reading order.
The product reference is the front door to the project. It answers what this product is, who lives with it, and which module owns each fact before sending a reader into module detail.
It is not the brief. The brief preserves what was learned and where it came from. The product reference states the accepted product picture. It is not a master specification either: field-level contracts and functional requirements stay in the module that owns them.
The eight sections
1 — Overview
State the purpose, scope, operating context and the authority map. Link every document family and say what it owns.
2 — Actors
Declare one controlled vocabulary for people who act. Use one name per person across every module. Name a party, system or legal entity separately when it does not itself perform an act.
Avoid placeholders such as user, system or domain owner. If no human actor owns an outcome, write the outcome directly instead of inventing a role.
3 — Domain model
Show only cross-module concepts and the module that writes each one. A product concept may have several module-owned records; similarity does not make them one lifecycle.
Field-level contracts stay module-local. The root model exists to make ownership and boundaries visible, not to duplicate every entity.
4 — Modules
For each module, state:
- the facts it owns and writes;
- the facts it reads from named neighbours;
- its public surface;
- the link to its module reference;
- the link to its work register.
A module that owns no facts is a query surface or adapter. Say so instead of pretending every box is a domain.
5 — Architecture
Show boundaries, dependency direction, integration style and deployment shape. Keep the overview descriptive. Link to decision records for choices whose means are expensive to reverse.
6 — Journeys
Show the end-to-end paths that cross modules. A journey cites the rules it illustrates; it does not become another owner of those rules.
7 — Open questions
Keep only questions with no single module owner: a cross-product policy, a boundary decision, or a service commitment. Module-local uncertainty stays in the corresponding module reference.
8 — Vocabulary
Carry the business term, its precise meaning and its single English code identifier. This is the normative lexicon used by every module.
A rendered outline
Worked example
Equipment Hire — product reference
A neutral product with three modules. The outline is stable even as its contents grow.
- Overview — reserve and collect maintained equipment.
- Actors — customer, depot operator, fleet manager.
- Domain model — equipment, reservation, handover.
- Modules — catalog, booking, handover.
- Architecture — module boundaries and public surfaces.
- Journeys — reserve → prepare → collect → return.
- Open questions — product-wide decisions only.
- Vocabulary — business terms ↔ code identifiers.
View source
# Equipment Hire
## 1. Overview
## 2. Actors
## 3. Domain model
## 4. Modules
## 5. Architecture
## 6. Journeys
## 7. Open questions
## 8. VocabularyWhat changes where
| Change | Update |
|---|---|
| A new actor works across the product | product reference, then affected module actor subsets |
| A module gains a field or invariant | that module reference only |
| A story ships | that module work register only |
| A module boundary moves | product reference and its accepted decision record |
| A cross-module journey changes | scenario and links to the owning requirements |
Do not turn the product reference into a second copy of every module. If a rule has a module owner, the root document links to it.