RTS questionnaire · Q43 · Design documentation proof

Have you created and maintained design documentation such as ER diagrams, database schemas, API contracts, component/service architecture diagrams, and business workflows?

The five artefact types, each with the same three answers: what it contains, who reads it, and the mechanism that stops it going stale. The argument running through all of them is that an artefact written beside the thing it describes will always lose.

Status: reviewed Live design-documentation workflow Docs as code · Generated artefacts · Staleness gates Jump to live proof ↓

43. Design documentation and its artefacts

Answer as submitted

“Yes — I create and maintain these artefacts, and I treat keeping them current as part of the work rather than as an afterthought.”
Technical decision: expand. The submitted line names the artefacts and the intention. This page is the separate, detailed version, and it takes the harder half seriously: maintained means a mechanism, not a resolution. Each artefact has one declared source of truth, is generated from it wherever a generator exists, is regenerated in the same pull request that changes the source, and is guarded by a gate that fails when the two disagree.

Expanded answer

Yes, and the design decision behind all five artefacts is the same one: put the truth in one place and derive everything else from it. ER diagrams are a view of the schema rather than a document beside it — generated from the migrations, so the picture cannot show a dropped column or miss one added on a Friday — at two levels because there are two audiences, a conceptual model the business can read and a physical one with types and keys that the team reviews the change against. Database schemas are the DDL itself under version control, with forward-only migrations applied by CI and a data dictionary generated from it; the column comment is the only place a change of meaning gets recorded, so it is part of the review rather than an ornament. API contracts are machine-readable documents with a generator on one side and a validator on the other, which is what distinguishes them from a specification in a wiki: OpenAPI generated from the implementation or written first and asserted against it, event schemas in a registry with a compatibility mode, and a breaking-change diff in CI. Component and service architecture follows the C4 levels so each diagram answers one question, with the container and component views generated from the deployment manifests and the service catalogue — because the manifests are executed by the platform and therefore cannot be wrong — and with ownership and dependencies recorded as data so a review can ask whether an edge is permitted rather than squinting at a picture. Business workflows are the exception to generation, because the value is the shared understanding: the process is modelled with the owner rather than presented to them, in a versioned model that includes the exception and escalation paths, which is where the process actually lives. And the mechanism that holds it together: a documentation pipeline in the repository, where a generated artefact is regenerated in the same pull request as its source, the docs site is built from the repository on every merge so a document cannot exist outside version control, and prose is reserved for the one thing no generator can produce — the why.

ArtefactSource of truthHow it is kept current
ER diagramthe migrationsgenerated; the committed file is compared against the generator output in CI
Database schemathe DDL under version controlforward-only migrations reviewed in a pull request; the dictionary is generated and shows missing where a comment is absent
API contractthe implementation, or the spec asserted against itdrift test against the running application, plus a breaking-change diff on every change
Architecture diagramsthe deployment manifests and the service cataloguegenerated in CI; findings open a ticket with an owner instead of failing the build
Business workflowsthe process model agreed with the ownerversioned in the repository; a process change requires the model to change in the same pull request
The mechanismthe documentation pipelineone declared source per artefact, generation in CI, and prose only for the why

Live design-documentation workflow proof

The running component below changes its artefact/result view through real event binding. Select an artefact to see what it contains, who reads it, and the mechanism that keeps it true.

LIVE PREVIEW
RUNNING
DESIGN DOCUMENTATION WORKFLOWRUNNING

Choose a design artefact

Select an artefact to inspect what it contains, who reads it and how it stays current.

$ entities, attributes and cardinality · generated from the migrations rather than drawn · a conceptual view for the business and a physical one for the team

The ER diagram is a view of the schema rather than a separate document: it is generated from the migrations, so it cannot show a table that no longer exists or miss one that was added on a Friday afternoon. There are two levels because there are two audiences — the conceptual model the business can read, and the physical one with types and keys that the team reviews the change against.

hand-drawn ER diagrams that can go stale: 0
the physical diagram generated from the migrations: on every release
conceptual models reviewed with the business owner: yes
an entity in a diagram with no table behind it: 0

What the documentation discipline buys

Rules I apply. Declare one source of truth per artefact and derive everything else from it, because two copies of the same truth means one of them is wrong; generate every artefact a generator can produce, since a diagram drawn once is a diagram that was current once; regenerate the artefact in the same pull request as the source change, because a separate documentation ticket never competes successfully with the next feature; keep the generated file in the repository so its diff is visible in review; reserve prose for the why — alternatives rejected, constraints, consequences — and accept that everything else is regenerable; name the audience of each artefact, because a document written for everybody is read by nobody; build the docs site from the repository on every merge so a document cannot exist outside version control; and give each finding an owner, since a report addressed to nobody is a report nobody fixes.
Boundary for Q43: this page covers the artefact types and the mechanism that keeps them current. The low-level design work itself — responsibilities, error-path sequences, the review before coding — is on the Q42 proof page; the API contract as a lifecycle is on Q49; the schema design decisions are on Q47; and the service catalogue the architecture view is generated from is on Q44.

Source files

Select a file to inspect the proof with syntax highlighting and line numbers. The first file is the code running the component above; the others are the ER and dictionary generator, the architecture diagram generator with its drift report, and the documentation pipeline that declares a source of truth and a staleness gate per artefact.

Acceptance criteria

RTS Questionnaire · Question 43 proof · answers/q43-proof.html · answers grounded in the CV_MCG portfolio of Manuela Cortés Granados.