Document a project

Use this guide when starting a project or repairing a documentation set whose rules and progress have drifted into several files.

The finished result has three obvious entry points:

product reference  →  module reference  →  module work register
whole product          owned rules           delivery progress

The example is Equipment Hire, a neutral product used only to demonstrate the structure.

1. Inventory existing authority

Search before creating files. For every existing brief, requirements document, ADR, roadmap, backlog and scenario, record what it currently claims to own.

Keep an existing document when it already has one clear role. Where two files own the same rule, choose the future owner and write a migration proposal before moving content.

2. Install the skeleton

Fit the structure to the repository's existing module folders:

docs/
  index.html
  delivery-plan.md
  decisions/
  scenarios/

product/modules/
  catalog/docs/
    index.html
    work-register.md
  booking/docs/
    index.html
    work-register.md
  handover/docs/
    index.html
    work-register.md

CONTRIBUTING.md

Do not create product/modules/ when the repository already calls the boundary features/, services/ or something else. The documentation follows the code's domain boundary; it does not impose a parallel tree.

3. Write the product reference

Use the fixed eight-section order from the product reference. Begin with the authority map, then name the actors and module ownership before adding detail.

## 2. Actors

`customer` · `depot operator` · `fleet manager`

## 3. Domain model

| Concept | Owning module | Other readers |
| --- | --- | --- |
| Equipment and availability | Catalog | Booking, Handover |
| Reservation and quoted price | Booking | Handover |
| Collection and return record | Handover | Catalog, Billing |

One actor name means one person throughout the set. One fact has one writing module. These two constraints prevent vocabulary and ownership from forking as the project grows.

4. Write each module reference

Create the same five sections in every module:

# Booking

## 1. Overview
## 2. Actors
## 3. Domain model
## 4. Open questions
## 5. Functional requirements

The overview names the facts the module writes. Actors are a subset of the root vocabulary. The domain model defines those facts at field level. Open questions stay local unless their answer changes another module's boundary.

Group requirements by stable domain clusters, then render each as a collapsible ID + imperative title row. The complete rendered and highlighted example is in The module reference.

5. Add the work register

Place work-register.md beside the module reference. State its non-normative role at the top, declare the status set, then group stories by WBS epic.

# Booking delivery register

Non-normative delivery plan. The functional requirements own product behaviour;
this register owns grouping, order and status. Stories cite requirements and
never restate their rules.

Statuses: `planned` · `in progress` · `shipped` · `withdrawn`.
A delivery gate is an annotation, not a status.

Use the rendered work-register example for every epic.

6. Prove the links

Trace one outcome in both directions before filling the entire set:

The chain is complete when:

• the root module map links the Booking reference and work register;
• BKG-001 is defined exactly once;
• story 01.01 links to BKG-001 rather than repeating it;
• the implementing use case and its tests cite BKG-001;
• the documentation checker can report uncovered and duplicate IDs.

7. Add cross-module material only once

The master delivery plan links module WBS codes to sequence integration work and demonstrations. Scenarios link requirements to tell end-to-end journeys. ADRs explain expensive-to-reverse technical means. None copies module rules.

8. Keep it current through ordinary work

Run documentation checks in the same change as any authority, link or requirement-ID edit.

Completion checklist

• The root reference uses all eight sections.
• Every module reference uses all five sections.
• Every fact has one writing module.
• Actors come from one controlled vocabulary.
• Requirements contain no implementation or delivery status.
• Work registers contain no copied business rules.
• Every story links requirements and every epic states its gate.
• Cross-module plans and scenarios link instead of duplicating.