Skip to content

ADR Process and Documentation Conventions

1. Purpose

HybridOps documentation is governed, reproducible, and verifiable.

This ADR defines:

  • when to write each governed document type (ADR, contract, standard, runbook, HOWTO, CI guide, showcase)
  • governance and lifecycle rules for ADRs
  • cross-linking rules so readers can follow decision → contract/standard → procedure → evidence

Conventions that must be referenced broadly are published as standards under docs/architecture/standards/.

2. Documentation types

2.1 ADRs

ADRs capture architectural decisions and trade-offs.

Write an ADR when a decision:

  • impacts multiple components, environments, or repositories
  • carries long-term cost/risk or operational consequences
  • requires a durable reference for maintainers and reviewers

2.2 Contracts

Contracts define normative behaviour and stable interfaces. Contracts use MUST/SHOULD semantics and state change-control expectations.

Contracts live under docs/architecture/contracts/.

2.3 Standards

Standards define repository-wide conventions that apply across contracts, runbooks, guides, and platform content.

Standards live under docs/architecture/standards/.

2.4 Runbooks

Runbooks are operator procedures for incidents, drills, and repeatable day-2 operations.

Runbooks describe:

  • preconditions and safety checks
  • step-by-step execution
  • verification and rollback
  • evidence capture locations

2.5 HOWTOs

HOWTOs are task-oriented implementation guides intended for learning and repeatable build steps.

HOWTOs are not incident procedures.

2.6 CI guides

CI guides document delivery pipelines and release mechanics, including guardrails and evidence outputs.

2.7 Showcases

Showcases are end-to-end narratives that connect ADRs, contracts/standards, procedures, and evidence into reviewer-facing stories.

3. Lifecycle and status

3.1 ADR status values

  • Proposed – Draft; under consideration.
  • Accepted – Adopted; should be implemented and followed.
  • Deprecated – Still documented but no longer recommended.
  • Superseded – Replaced by a newer ADR.
  • Rejected – Considered but not adopted.

When superseding, update both ADRs:

  • older ADR: set status: Superseded and add superseded_by
  • new ADR: add supersedes

3.2 Draft handling

Documents marked draft: true are excluded from generated indexes.

4. Category codes

All governed documents use the same category code scheme:

Code Category
00 Governance & process
01 Networking
02 Platform
03 Security
04 Observability
05 Data & storage
06 CI/CD & automation
07 Disaster recovery
08 Cost optimisation
09 Compliance

The category code is the primary anchor for numbering and navigation.

5. IDs and numbering

5.1 Format

Each governed document family uses a dedicated prefix and a category-based numeric block:

  • ADR: ADR-CCNN
  • Runbook: RB-CCNN
  • HOWTO: HOWTO-CCNN
  • CI guide: CI-CCNN

Where:

  • CC is the category code (00–09)
  • NN is the sequence within the category (01–99)

Examples:

  • ADR-0001 (governance)
  • ADR-0205 (platform)
  • ADR-0622 (CI/CD & automation)

5.2 Rule: ID must match filename prefix

The frontmatter id MUST match the filename prefix.

5.3 Stability

IDs are stable identifiers. Do not renumber accepted documents. If a document must move categories, it is superseded by a new ID and linked via supersedes / superseded_by.

6. Topic slugs and cross-document linking

6.1 Topic slug

A topic slug is a stable kebab-case identifier for a capability or pattern, for example:

  • gitops-bootstrap
  • proxmox-sdn
  • packer-proxmox-templates
  • gcp-ha-vpn-bgp

6.2 When slugs should match

Use the same topic slug across ADR, runbook, and HOWTO only when they describe the same capability.

7. Storage conventions

7.1 ADRs

  • Path: docs/adr/
  • Filename: ADR-<CCNN>-<topic-slug>.md

7.2 Contracts

  • Path: docs/architecture/contracts/
  • Filename: contract-defined naming (typically RFC-based)

7.3 Standards

  • Path: docs/architecture/standards/
  • Filename: standard-defined naming

7.4 Runbooks

  • Path: docs/ops/runbooks/<lifecycle-category>/
  • Filename: RB-<CCNN>-<topic-slug>.md

Lifecycle category is operational (bootstrap, dr, burst, ops, platform, networking, security).

7.5 HOWTOs

  • Path: docs/howto/<optional-subcategory>/
  • Filename: HOWTO-<CCNN>-<topic-slug>.md

7.6 CI guides

  • Path: docs/ops/ci/
  • Filename: CI-<CCNN>-<topic-slug>.md

7.7 Templates

Templates MUST include:

  • draft: true

Templates live under the relevant area or a dedicated templates/ subfolder.

8. Frontmatter requirements

8.1 Required fields (all governed documents)

  • title
  • category
  • draft
  • access

Recommended:

  • tags
  • domains
  • owners

8.2 Family-specific fields

  • ADRs: id, status, date, supersedes, superseded_by, links
  • Use descriptive link text.
  • Prefer relative links within the docs tree.
  • Avoid marketing language in operational documentation.
  • Avoid bare URLs except where required in a dedicated references section.

10. Evidence linkage

The standard trace chain is:

ADR (why) → contract/standard (what must remain stable) → runbook/HOWTO (how) → evidence artefacts (proof)

Evidence artefacts live under repository output/ trees and are referenced from:

  • runbooks (verification section)
  • showcases (proof section)
  • evidence maps

11. Migration rules (legacy filenames)

Legacy documents may exist with older names.

Migration approach:

  • new documents MUST follow this ADR
  • legacy documents SHOULD be renamed opportunistically when edited
  • inbound links MUST be updated during migration

13. Benefits

Following these conventions ensures:

  • deterministic indexing and navigation
  • clear cross-referencing from intent to operation
  • maintainability as the platform surface evolves