Docs as Code - documentation artifacts as versioned text
Documentation is a text artifact in git: diffable, PR-reviewed, and rendered natively on
GitHub/GitLab. That is the whole stance - it is what keeps docs from rotting - and it applies to
any subject, not just architecture: an API flow, a schema, a process, a decision. Diagrams live
inline in the doc they explain (a standalone .mmd only when several docs share one).
Structure goes in diagrams; rationale goes in ADRs; the two link to each other, never restate
each other.
Pick the artifact
| Documenting |
Use |
Reference |
| An interaction ordered in time - API call chain, auth handshake, retry/timeout, event choreography |
Mermaid sequence diagram |
references/mermaid-sequence.md |
| A relational schema sketch - a handful of tables, keys, cardinality |
Mermaid ER diagram |
references/mermaid-er.md |
| A load-bearing decision - structure, cross-cutting NFRs, external dependencies, interfaces |
ADR - Nygard by default, MADR 4 when options were weighed |
references/adr.md |
| System-in-environment or deployable-parts structure, incl. for stakeholders |
C4 context/container view |
references/c4.md |
| THIS project's architecture map |
owned by project-architecture-analyzer (flowchart + module table per its doc-shapes contract) - supplement it, never re-draw it |
|
Branching business logic is a flowchart, not a sequence diagram; static structure is ER/C4, not
sequence. When a diagram and an ADR both apply (a decision that changed structure), write both -
the ADR names the why, the diagram shows the outcome, each links the other.
Mermaid ground rules (both diagram types)
- Fence with the language id exactly
mermaid - renders natively on GitHub, GitLab, Azure
DevOps, and the VS Code preview, no plugins. Standalone diagrams are .mmd files.
- Renderers lag the library (GitLab and wiki plugins run older majors) - preview on mermaid.live,
then validate on the actual target platform before relying on newer syntax.
- Never hardcode a theme in an init directive - it breaks the reader's dark/light mode on GitHub.
Prefer YAML frontmatter (
title: + config:) over the deprecated init directive.
- Accessibility:
accTitle: + accDescr: inside the diagram, plus one plain-text sentence in
the surrounding Markdown - screen readers do not get node relationships from the SVG.
- Comments are
%% on their own line. Colors in rect/box regions take rgb()/rgba() only - hex
breaks there (hex is fine in theme variables, which accept ONLY hex).
- Mermaid ignores misspelled config keys silently but breaks on malformed syntax; the word end
unquoted breaks flow/sequence diagrams - wrap it as "end".
- One diagram per concern, sized to one screen. A diagram that needs scrolling is two diagrams.
The bar
Every diagram carries a title (and a legend when shapes/colors carry meaning); every ADR lists
its consequences including the negative ones. An artifact that would drift silently gets wired to
its source instead: generate ER diagrams from the live schema, regenerate in CI, supersede ADRs
rather than rewriting them.
1---2name: docs-as-code3description: Authoring conventions for documentation as versioned text artifacts - the docs-as-code practice: Mermaid diagrams (sequenceDiagram for interaction flows, erDiagram for schema sketches), decision records (ADR - Nygard + MADR 4), and C4 model views (context/container). Load before writing or reviewing ANY documentation artifact of these types, whatever the subject - a sequence/ER/C4 diagram in Markdown, an ADR or decision-log entry, or a diagram-tooling choice (Mermaid vs DBML vs Structurizr). Routes per doc type to references/. Triggers on sequence diagram, ER diagram, entity relationship, ADR, decision record, decision log, C4, container diagram, context diagram, docs-as-code - and on mermaid for those diagram types (other Mermaid forms get only the generic ground rules here). NOT the repo's committed architecture capture (project-architecture-analyzer owns <docs-path>/architecture/), not Markdown prose style (markdown-style), and not DB design itself (database-conventions).4---56# Docs as Code - documentation artifacts as versioned text78Documentation is a text artifact in git: diffable, PR-reviewed, and rendered natively on9GitHub/GitLab. That is the whole stance - it is what keeps docs from rotting - and it applies to10any subject, not just architecture: an API flow, a schema, a process, a decision. Diagrams live11inline in the doc they explain (a standalone `.mmd` only when several docs share one).12Structure goes in diagrams; rationale goes in ADRs; the two link to each other, never restate13each other.1415## Pick the artifact1617| Documenting | Use | Reference |18|---|---|---|19| An interaction ordered in time - API call chain, auth handshake, retry/timeout, event choreography | Mermaid sequence diagram | `references/mermaid-sequence.md` |20| A relational schema sketch - a handful of tables, keys, cardinality | Mermaid ER diagram | `references/mermaid-er.md` |21| A load-bearing decision - structure, cross-cutting NFRs, external dependencies, interfaces | ADR - Nygard by default, MADR 4 when options were weighed | `references/adr.md` |22| System-in-environment or deployable-parts structure, incl. for stakeholders | C4 context/container view | `references/c4.md` |23| THIS project's architecture map | owned by `project-architecture-analyzer` (flowchart + module table per its doc-shapes contract) - supplement it, never re-draw it |2425Branching business logic is a flowchart, not a sequence diagram; static structure is ER/C4, not26sequence. When a diagram and an ADR both apply (a decision that changed structure), write both -27the ADR names the why, the diagram shows the outcome, each links the other.2829## Mermaid ground rules (both diagram types)3031- Fence with the language id exactly `mermaid` - renders natively on GitHub, GitLab, Azure32 DevOps, and the VS Code preview, no plugins. Standalone diagrams are `.mmd` files.33- Renderers lag the library (GitLab and wiki plugins run older majors) - preview on mermaid.live,34 then validate on the actual target platform before relying on newer syntax.35- Never hardcode a theme in an init directive - it breaks the reader's dark/light mode on GitHub.36 Prefer YAML frontmatter (`title:` + `config:`) over the deprecated init directive.37- Accessibility: `accTitle:` + `accDescr:` inside the diagram, plus one plain-text sentence in38 the surrounding Markdown - screen readers do not get node relationships from the SVG.39- Comments are `%%` on their own line. Colors in rect/box regions take rgb()/rgba() only - hex40 breaks there (hex is fine in theme variables, which accept ONLY hex).41- Mermaid ignores misspelled config keys silently but breaks on malformed syntax; the word end42 unquoted breaks flow/sequence diagrams - wrap it as "end".43- One diagram per concern, sized to one screen. A diagram that needs scrolling is two diagrams.4445## The bar4647Every diagram carries a title (and a legend when shapes/colors carry meaning); every ADR lists48its consequences including the negative ones. An artifact that would drift silently gets wired to49its source instead: generate ER diagrams from the live schema, regenerate in CI, supersede ADRs50rather than rewriting them.
envoydev