Module 9: Start Here

Overview

Module 8 made one decision legible to the people who had to agree with it. This module makes the practice legible.

How do you turn architecture from a person into a process the organisation can run?

The argument for caring is short: individual good decisions do not compound. A process does. An architect who makes fifty excellent decisions and records none of them leaves an organisation that has to re-derive all fifty. One who records them leaves something that keeps working after they have gone.

This is also where the two threads of this guide meet. Documentation is no longer written only for colleagues — it is context for machines, and the discipline that makes it retrievable is the same discipline that makes it useful to a new engineer.

The organising idea

One distinction runs through the whole module and resolves most of the confusion about architectural documents:

The HLD describes. The ADRs explain.

Keeping those separate is what lets the description be revised freely as the system changes, without destroying the decision history that tells you why it is shaped that way. Conflate them and you get a document that is either permanently out of date or has had its reasoning edited away.

How the module is built

Two sections: the artifacts, then the process around them.

graph TD
  subgraph S1["Section 1 — The artifact set"]
    A["1 · Which artifacts<br/>and why"]
    B["2 · ADRs in<br/>practice"]
    C["3 · ADR recovery"]
    D["4 · The HLD and<br/>the proposal"]
    E["5 · Templates and<br/>template theatre"]
    A --> B --> C --> D --> E
  end
  subgraph S2["Section 2 — Process, context and governance"]
    F["6 · Collaborative<br/>design"]
    G["7 · Documentation<br/>as Code"]
    H["8 · Documentation<br/>as Context"]
    I["9 · Governance sized to<br/>the organisation"]
    J["10 · The review shift,<br/>and real-world texture"]
    F --> G --> H --> I --> J
  end
  E ==> F
  J ==> K(["Workbook — Exercise 9"])

  classDef s1 fill:#5B8FB9,stroke:#4A7A9E,stroke-width:2px,color:#ffffff
  classDef s2 fill:#E8A33D,stroke:#C4832A,stroke-width:2px,color:#ffffff
  classDef cap fill:#D9695B,stroke:#B4483A,stroke-width:2px,color:#ffffff
  class A,B,C,D,E s1
  class F,G,H,I,J s2
  class K cap

Section 1 is what you write. Section 2 is how it gets written, where it lives, and who enforces anything.

Section 1 — The artifact set

1. Which artifacts and whySix documents, who reads each, how long it lives — and the three to introduce first.

2. ADRs in practiceThe highest-leverage artifact, and the field everyone sanitises.

3. ADR recoveryReconstructing decisions that predate the practice, without inventing history.

4. The HLD and the proposalOne describes the system, one requests a decision. Conflating them breaks both.

5. Templates and template theatreTemplates lower the cost of doing the right thing, and invite doing none of it.

Section 2 — Process, context and governance

6. Collaborative designEvent Storming, bounded contexts, and running a session that ends in decisions.

7. Documentation as CodeDocs beside the code, diagrams as text, reviewed the same way.

8. Documentation as ContextStructuring docs so retrieval works — the same discipline that serves humans.

9. Governance sized to the organisationBoards, standards, and why most of it is premature at your headcount.

10. The review shift, and real-world textureReview protocols for generated designs, outdated docs, and knowledge nobody will write down.

How to work this module

About seven hours, and the split is unusual:

1. Read the ten topics — about 2.5 hours.

2. Optional — Workbook exercise 9 — about 4.5 hours. The heaviest in the guide, five artifacts, and one of them asks you to reconstruct your own earlier reasoning.

In the workbook

Five artifacts for Lintel:

• An ADR set capturing the significant decisions from Modules 3–7, written retroactively
• An HLD for the AI support platform, readable by someone who has not taken this guide
• An architecture proposal in template form, ready to submit
• A documentation structure that works as onboarding material and as retrieval context
• A process proposal — the minimum governance you would introduce in six months, with what you would deliberately delay

Before you start

You need your Modules 3–7 artifacts. The ADR set is a recovery exercise on your own work, and it is uncomfortable for a specific reason: you will find decisions whose reasoning you can no longer fully reconstruct, made a few weeks ago by you.

Module 8’s organisational reading matters here too. Governance that fits a generative culture fails in a bureaucratic one, and the process proposal has to be sized for the organisation you actually read rather than the one in a textbook.

Check your understanding

Answer now, revisit at the end.

1. Name a decision in a system you know whose reasoning exists only in someone’s head. What happens when they leave?
2. When did you last read documentation that was wrong? What did it cost, and would no documentation have been better?
3. If an agent had to find out why a boundary in your system exists, where would it look?

→ Start with Which artifacts and why.