Documentation Style¶
Use this guide for development documentation. Domain terminology and architectural decisions remain authoritative in Domain and Architecture Decision Records.
Status and authority¶
- State whether a page is normative, a current implementation guide, planned work, or historical.
- Give volatile implementation snapshots a verification date and a repeatable check where possible.
- Write accepted but unimplemented behavior as “decided, not implemented,” not in the present tense.
- Historical pages use past tense and link to the current guide that replaces them.
- OpenAPI and JSON Schema files define wire structure. Prose explains semantics and must not invent fields or events.
Every page needs YAML front matter with title, status, and last_reviewed. Use the status values normative, current, planned, historical, exercise, or audit, adding a concise qualifier only when it prevents ambiguity.
Terms¶
| Term | Use |
|---|---|
| Brand, Brand User, Consumer, Account, Visitor, Fridge, Shopping List, Verdict | Capitalize when referring to the domain concept defined in the domain model. Use lowercase for ordinary non-domain meanings. |
| bounded context | A domain boundary. Do not use it as a synonym for service; the API Gateway is a service edge but not a bounded context. |
| domain event | A fact recognized inside a bounded context. It may remain private. |
| stored event | A domain fact persisted in an event-sourced aggregate stream. |
| integration event or integration fact | A versioned message published between services over Kafka. |
| read model | Query-shaped derived state. Use “view” only for an actual database view. |
| alert | A Fridge freshness notification fact. It is not a personal Verdict. |
| current | Include an “as of” date or verification command. Avoid it for invariants. |
Use US English in new prose (behavior, localized, honoring) while preserving code identifiers, quoted user-interface text and official names.
Tone and evidence¶
- Prefer direct, testable statements to assurances, metaphors and promotional claims.
- Do not use “obvious,” “real,” “honest,” “exactly,” or “deliberately” as rhetorical emphasis.
- Do not claim completeness, conformance, production readiness or regulatory applicability without a stated scope and evidence.
- Cite primary sources for standards, regulation, provider behavior and time-sensitive external claims. Record the verification date when the claim can change.
- Label illustrative code and screenshots. A screenshot proves only the environment and time named in its capture metadata.
Links, paths and diagrams¶
- Link to the normative page instead of restating its full inventory.
- Keep manually listed file paths short and verify them against the current tree.
- Prefer Mermaid for diagrams that can remain readable as text. When a Drawio source is required, edit the source and run make docs-diagrams; use make docs-diagrams-check from a clean tree to detect a stale committed PNG.
- Give wide raster diagrams a full-size link and label their status, environment and verification date.
Run make docs-build before committing documentation. Run make check before opening a pull request because the full gate also validates contracts, source boundaries and deployment files.