Creating a Procedures Module

A procedure is a repeatable recipe an operator follows to produce a standard outcome. It is prescriptive (numbered steps) and recurring (runs on a cadence or on demand). It is defined by the outcome it produces, not the tool used to produce it.

1. When to use this type

Create a Procedures module when non-engineer staff produce business outcomes through the system on a repeating basis. Typical procedures: running a data import, processing an inventory lifecycle, generating a periodic report, finalising an event.

It IS a procedure when… It is NOT a procedure when…

A staff member runs it to produce a defined output

An engineer runs it to keep the system healthy → Operations

It recurs (cadence or on demand)

It is a one-off incident recovery → Runbooks

It is a numbered set of steps

It explains/teaches without prescribing steps → User Guide

See the two axes for the full discriminator.

2. Standard structure

modules/procedures/
├── nav.adoc
└── pages/
    ├── index.adoc                 # Catalogue of procedures, grouped by area
    ├── <produce-outcome-a>.adoc   # One procedure per outcome
    └── <produce-outcome-b>.adoc

Group the index by outcome area (Imports, Inventory, Reporting, …), not by tool. Each page is one procedure.

3. Page template

Each procedure answers six questions, in order. Copy templates/procedure-template.adoc from the doc-standard repository, or use this skeleton:

= <Verb the outcome>: <Subject>
:description: <one line — what standard outcome this produces and for whom>

== Outcome
<What standard output this produces, and who consumes it.>

== Cadence
<When it runs — a schedule, an event boundary, on request.>

== Prerequisites
<What must be true before starting; required inputs and access.>

== Steps
. <Numbered step, with the concrete command / screen / parameter>
. <Expected result and any verification gate>

== Verification
<How to confirm the outcome is correct — spot-checks, reconciliations.>

== Recovery
<What to do when a step produces an unexpected result.>

== References
<The requirement it fulfils, the design it operates, related work items.>

Cross-link, don’t restate. A procedure references the design for how the feature works and the user guide for what the screens mean. It carries only the steps and the concrete values.

4. Flexibility

  • Small project: a single index page listing a handful of short procedures may be enough — one page per procedure only once they grow detailed.

  • Mechanism in transition: when a procedure is SQL today and UI tomorrow, keep one page and update the Steps; the procedure’s identity is its outcome, so it does not move or split.

  • Shared steps: factor a sub-procedure reused by several procedures into its own page and xref to it, rather than copy-pasting steps.

5. Quality checklist

  • Each page names a concrete outcome and its consumer.

  • Cadence is stated.

  • Steps are numbered, concrete, and verifiable; no "obvious" gaps.

  • A Recovery path exists for the steps that can fail.

  • Links to the requirement/design it operates and to any user guide.

  • No engineer-only system-health content (that belongs in Operations).

6. Common pitfalls

  • Filing by tool, not outcome — "the SQL scripts" is not a procedure; "produce the monthly sales report" is.

  • Mixing audiences — SRE cache-eviction steps do not belong beside an operator’s import recipe.

  • Restating the design — link to it; keep the procedure to steps and values.

  • Silent prerequisites — if access, a file, or a prior procedure is required, say so up front.

7. Related