How This Documentation Is Structured

This page is the map. It explains what kind of document goes where and, more importantly, how to decide when you are holding a new document and don’t know which module it belongs to.

The two scopes

EMS documentation lives in two places, split by reach:

Solution-wide — this site, docs-event. Anything that spans more than one application, or describes the system as a whole: requirements, architecture, cross-cutting design, operations, procedures. When in doubt, it goes here.
Project-specific — a sub-project’s own docs/ (for example registration-portal/docs). Only documentation that is meaningless outside that one codebase: that app’s internal design, its local build quirks, its component-level implementation notes.

The rest of this page is about the solution-wide site.

The mental model: two axes

The hard documents to file are the operational ones. The reason is that two different questions are easy to confuse. Ask them in order and the answer falls out:

Axis	Question
Audience	Who reads this — an engineer keeping the system alive, or a staff member / operator doing their job through the system?
Nature	Is this recurring (runs on a cadence or on demand) or exceptional (a one-off incident or correction)? And is it prescriptive (numbered steps) or descriptive (explanation and examples)?

Axis

Question

Audience

Who reads this — an engineer keeping the system alive, or a staff member / operator doing their job through the system?

Nature

Is this recurring (runs on a cadence or on demand) or exceptional (a one-off incident or correction)? And is it prescriptive (numbered steps) or descriptive (explanation and examples)?

The audience axis is the one most often missed. "Operations" feels like a single bucket, but it contains two audiences: the engineer evicting a cache, and the operator producing a report. They do not belong together.

The operational quadrant

	Recurring / steady-state	Exceptional / one-off
Technical (engineer / SRE)	Operations keep the system healthy: cache, observability, management API, SMTP	Runbooks surgical recovery & data correction: restores, reconciliations
Business (operator / staff)	Operational Procedures produce a standard outcome: run imports, process number returns, generate a report	(rare — fold the one-off into a procedure, or if it is really an incident it is a Runbook)

Recurring / steady-state

Exceptional / one-off

Technical (engineer / SRE)

Operations
keep the system healthy: cache, observability, management API, SMTP

Runbooks
surgical recovery & data correction: restores, reconciliations

Business (operator / staff)

Operational Procedures
produce a standard outcome: run imports, process number returns, generate a report

(rare — fold the one-off into a procedure, or if it is really an incident it is a Runbook)

Orthogonal to the quadrant — the learning material — sits the User Guide: descriptive explanations and worked examples for staff learning a feature. A User Guide teaches understanding; a Procedure gives the steps. They cross-link, they do not duplicate.

A procedure is defined by the outcome it produces, not the tool it uses. A report generated by SQL today and by the admin portal tomorrow is the same procedure — it stays in Operational Procedures either way. Don’t file by mechanism.

The full module map

Documentation type Module(s) What belongs here

Documentation type	Module(s)	What belongs here
Requirements	requirements, use-cases	What the system must do — functional requirements, and the formal per-screen use-case specs.
Design	common-design, `*-design`, `design-journal/`	How a feature is designed — cross-cutting design, per-application screen design, and the running design-decision journal.
Architecture	architecture, security	System-level structure and patterns — service patterns, integration, security architecture.
Operations (technical, steady-state)	operations	Keeping the system healthy: cache eviction, management API, observability, SMTP.
Runbooks (technical, exceptional)	runbooks	One-off recovery and data correction: surgical restores, cross-system reconciliations.
Operational Procedures (business, recurring)	procedures	Repeatable recipes that produce a standard business outcome: imports, number/tag lifecycle, reporting.
Guidelines & Help Guides (training)	user-guide	Feature explanations and worked examples for staff learning the system.
Build & Deploy	development, deployment	How to build, test, and deploy the system (engineer audience).

Requirements

requirements, use-cases

What the system must do — functional requirements, and the formal per-screen use-case specs.

Design

common-design, *-design, design-journal/

How a feature is designed — cross-cutting design, per-application screen design, and the running design-decision journal.

Architecture

architecture, security

System-level structure and patterns — service patterns, integration, security architecture.

Operations (technical, steady-state)

operations

Keeping the system healthy: cache eviction, management API, observability, SMTP.

Runbooks (technical, exceptional)

runbooks

One-off recovery and data correction: surgical restores, cross-system reconciliations.

Operational Procedures (business, recurring)

procedures

Repeatable recipes that produce a standard business outcome: imports, number/tag lifecycle, reporting.

Guidelines & Help Guides (training)

user-guide

Feature explanations and worked examples for staff learning the system.

Build & Deploy

development, deployment

How to build, test, and deploy the system (engineer audience).

Deciding where a new document goes

Is it specific to one codebase and meaningless elsewhere? → that project’s own docs/. Otherwise it is solution-wide and lives here.
Does it state what the system must do, or how it is designed/structured? → requirements / use-cases, common-design, or architecture.
Is it operational? Then ask the two axes:
1. Who runs it? Engineer keeping the system alive → operations (steady-state) or runbooks (exceptional). Operator producing a business outcome → procedures.
2. Is it teaching rather than instructing? → user-guide.

A single feature usually produces a family of documents across modules: a requirement (what), a design (how it is built), a procedure (how an operator runs it), and a user guide (how a person learns it). That is expected — each lives in its own module and they cross-link. Don’t try to make one document serve every audience.