Documentation as Code vs Architecture as Code · Architecture as Code: the course

All courses / Architecture as Code / Module 6 / Chapter 22

Learning objectives

After the lesson the participant can:

Distinguish Documentation as Code from Architecture as Code by purpose, audience, artefact type and success metric.
Explain why a modelling tool can serve as a source of truth where a diagram tool cannot.
Classify existing artefacts and tools as documentation or architecture and identify misuse.
Apply the five practices for integrating both disciplines in one repository.

Key concepts

Documentation as Code: A discipline that treats documentation as a first-class artefact in the codebase, with the primary goal of communicating how systems work, why decisions were made and how teams should interact with the technology. It targets human audiences.
Architecture as Code as structure and enforcement: The definition of a system's structure in a machine-readable format that can be validated, tested and automated, so that the implementation matches the intended design and constraints are enforced programmatically. It targets both humans and machines.
Model as the source of truth: The key advantage of modelling tools such as CALM and Structurizr: diagrams, documentation and compliance reports are all derived from the same underlying model, which ensures consistency and enables automated validation.
CALM: The Common Architecture Language Model, an open-source specification developed under FINOS and built on a JSON meta-schema. Its format is built around nodes, relationships, interfaces, controls, flows and metadata such as compliance tags.
Limitations of diagram tools: For Architecture as Code, diagram tools make the diagram itself the source of truth, capture limited metadata, allow no automated validation against policies and require manual synchronisation with the implementation.

Interactive exercises

Do them here and get feedback at once. Choose a card and then where it belongs, or drag it.

Interactive exercise 1 · Sort

Explaining or enforcing

Sort each goal, question or tool by the discipline to which the chapter assigns it.

Interactive exercise 2 · Scenario

Diagrams in Git, but is it Architecture as Code?

Read the situation and choose what the chapter's reasoning leads to. Each choice gives feedback.

Teaching plan

15 min	Teacher presents the two purposes with the questions each discipline answers, then the ten-row comparison table.
15 min	Side-by-side reading of a model definition and a text diagram of the same payment flow. Participants list what a tool could check in each.
10 min	Teacher explains how architecture feeds documentation and documentation explains architecture, and the five integration practices.
25 min	Exercise: classify the participant's own artefacts and tools and plan one integration.
10 min	Plenary: where diagrams are being treated as architecture, and what the consequence is.

Discussion

The book uses Mermaid for its own diagrams and explains why. When is an illustrative diagram the right choice, even in an organisation that practises Architecture as Code?
What can an architectural model never convey without accompanying documentation?
If your organisation measured documentation quality and architectural integrity as distinct metrics, which would look better today, and why?

Written exercise

Exercise · 25 minutes

Classify your artefacts: explained or enforced

List ten artefacts that describe the architecture of one system in your own organisation, such as diagrams, guides, decision records, models, modules and policies. For each one decide, using the chapter's comparative framework, whether it is Documentation as Code or Architecture as Code: who its audience is, whether a machine can validate it, and what its source of truth is. Mark every artefact that is used as if it enforced the architecture but is only a diagram or a narrative. Choose one of these and describe how it could be derived from a model instead. Finally write how the five integration practices would apply to this system, one sentence each.

Deliverable: A table of ten classified artefacts with audience, validation and source of truth, one proposal to derive an artefact from a model, and five integration statements.

Your work

Self-test

Choose an answer to see whether it is right, or open the answer below each question.

What is the first limitation of diagram tools for Architecture as Code that the chapter lists?
Show the answer
B. The diagram is the source of truth, with no underlying model to query or validate
With diagram tools the diagram is the primary artefact; there is no underlying model that can be queried, validated or used to drive automation. The diagrams are still version-controllable and reviewable.
According to the comparative framework, what is the validation focus of Architecture as Code?
Show the answer
D. Compliance verification, policy enforcement and drift detection
The framework gives compliance verification, policy enforcement and drift detection for Architecture as Code, and link checking, spelling, grammar and consistency for Documentation as Code.
Which three of CALM's core components does the chapter use to illustrate the approach?
Show the answer
A. Nodes, relationships and metadata
CALM is built around nodes, relationships, interfaces, controls, flows and metadata. The chapter illustrates it with three: nodes (services, databases, networks, people), relationships (connections, data flows, dependencies) and metadata (compliance tags, operational data, custom attributes).