Module 7: Documentation That Survives
Module introduction: documentation that survives
Why this module exists here
There's a question almost no team asks itself until it's already too late: if tomorrow the person who knows the most about this system leaves, how much goes with them? The honest answer, in most teams, is "too much". Not because no one wrote documentation —there's almost always a wiki, or a Confluence, or a folder of Google Docs—, but because that documentation doesn't survive: it was written once, became disconnected from the code, drifted out of sync with reality, and today no one opens it because no one trusts it. When the person who does know leaves, the knowledge goes with them, and the team discovers the hard way what the system does. This module is about the opposite: documenting in a way that the knowledge survives time, the turnover of people, and the onboarding of whoever arrives.
This whole guide teaches the human and organizational craft of being an architect. In module 1 you dismantled the myth of the role. In module 2 you saw how the organization shapes the system (Conway). In module 3 you learned to communicate with C4 and the ADR. In module 4, to lead without authority. In module 5, to translate business goals into quality attributes. In module 6, to design for change. All those modules produced knowledge: decisions, boundaries, trade-offs, the why of each thing. And all rested on an assumption they never said out loud: that this knowledge stays. It doesn't stay on its own. It lives in people's heads, and people leave. This module installs the discipline that prevents the knowledge from leaving with them: documentation that survives.
And here we have to be precise about the ecosystem frontier, because this module touches two tools you've already seen. C4 —the four zoom levels of a diagram— was taught thoroughly in module 3 of this very guide: how to draw it, which level for which audience. The ADR —the record of an architecture decision— comes from the sister guide architecture-decisions-and-tradeoffs: its mechanics, how it's written, how a decision is classified. This module does not re-teach either of the two. Here C4 and the ADR are pieces of a documentation system that has to last: not "how do I draw a Container" (that's M3) nor "how do I write an ADR" (that's the other guide), but "how do I make Mercado's C4 and ADR still be true and useful two years from now, when half the team is different". The module teaches the principle and the criterion of documentation that survives, not the specific tools in depth.
The case, seen from the knowledge: Mercado and the head that can leave
Mercado is the marketplace that accompanies us throughout the guide, and here we look at it through a new lens: the knowledge. Not the diagram of the system, but the map of who knows what. Remember its organization —five squads working on five modules: catalog, orders, payments, shipping, platform—. Behind each module there are concrete people who understand it, who can fix it on a Sunday at 3 a.m. when something goes down, who know why it's built the way it is.
That map hides a risk no architecture diagram shows. Look at the people who hold up each module:
Mercado's knowledge map (who can maintain each module)
catalog ── Ana, Beto, Caro (3 knowers)
orders ── Beto, Diego (2 knowers)
payments ── Elena (1 knower) <-- a single head
shipping ── Diego, Caro (2 knowers)
platform ── Ana, Elena, Beto (3 knowers)
catalog is held up by three people; platform, three. If one leaves, two remain. But payments —the module that charges the money, the most delicate in the system— is maintained by a single person: Elena. If Elena goes on vacation for two weeks, no one can touch payments with confidence. If Elena leaves the company, that module is left orphaned: no one else knows why it's built the way it is, what decisions hold it up, where the loose wires are. That's a single point of failure of knowledge, and it doesn't appear in any C4, in any org chart, in any performance metric. It appears only the day Elena hands in her resignation —when it's already too late—.
Mercado's architect doesn't fix this by asking Elena not to leave. People leave: it's normal, not an emergency. They fix it by making Elena's knowledge not depend only on Elena. And the cheapest way to do it isn't to clone Elena (training a second human expert takes weeks), but to document the stable part of payments —its boundaries, its decisions, the why of its design— so that this doc acts as a "knower who never leaves". The doc doesn't replace Elena; but Elena stops being the only insurance. That's the craft of this module, and —like everything in this guide— it can be measured.
Connection with the module. This is the map-lesson. It doesn't go deep into any of the pieces; it installs the thesis (most doc doesn't survive; documenting well is writing the stable, close to the code, to raise the bus factor), the vocabulary (living documentation, docs-as-code, bus factor, stable vs volatile doc, the C4+ADR+arc42 combo, the onboarding README) and the map of how each lesson builds the discipline. Lesson 2 explains why doc rots and what keeps it alive. Lesson 3 teaches docs-as-code: doc in the repo, reviewed in PRs, validated in CI. Lesson 4 assembles the C4 + ADR + arc42 system. Lesson 5 marks the rule that saves the doc: document the stable, not the volatile. Lesson 6 writes the README that onboards. Lesson 7 goes to the heart: the bus factor and knowledge sharing. And lesson 8 has you make Mercado's documentation survive on a real, executed case. Mind the frontier: C4 as a diagram is module 3 and the ADR as mechanics is architecture-decisions; here both are pieces of a doc system that must last.
And the usual promise: even though the topic seems like "writing text", the quantifiable is executed, not asserted. Each simulation runs with Python 3.14 and only the standard library, with fixed data, so the output of each "What to expect" block is the literal output of running the code. You can copy it and reproduce it identically.
An analogy: the manual the previous owner left you (or didn't)
Think of the day you move into a house you didn't build —you bought it or you rented it—, and of two versions of that day.
The house with no manual. You arrive, and there's nothing. No one left you a note. So you start discovering the house the hard way: it's night and you can't find the living-room switch, you grope the wall for half an hour. In winter the water comes out freezing and you don't know how to light the water heater —is it gas? where's the pilot?—, until a plumber charges you a visit to point out a knob. The kitchen power cuts out and you don't know which of the twenty breakers it is, so you switch them all off and test them one by one. One day the patio floods and you can't find the main water valve to shut it off —it's buried behind some pots the previous owner put on top—. Every thing the house does, you learn by suffering, week after week, and some you never learn: there's a valve on the roof you don't know what it's for and you'd rather not touch. The house works, but you live fighting with it because the knowledge of how it operates left with the previous owner.
The house with a manual. You arrive, and in the kitchen there's a folder the previous owner left you: "Welcome. The main water valve is in the garden, behind the rosebush, green cover. The water heater is gas: knob to the left of the garage, the pilot lights with the lighter hanging next to it. The kitchen breaker is the third from the top, labeled. The roof valve is for the solar heater; don't touch it in winter." In ten minutes you know how to operate the house. You don't discover anything the hard way: the previous owner distilled what they learned over years and handed it to you on one page. When the kitchen power cuts out, you go straight to the right breaker. When the patio floods, you shut the valve in thirty seconds. It's not that the house is better —it's the same house—; it's that the knowledge of how it operates survived the change of owner.
That folder is the documentation that survives of this module, and the analogy has three layers worth separating, because they're three distinct lessons:
- The folder exists and is true (living documentation, docs-as-code): a manual that says "the water heater is electric" is useless when it's actually gas —worse: it sends you down the wrong path—. The manual has to be synchronized with the real house. If the previous owner changed the heater and didn't update the note, the note became a trap. The doc that survives lives glued to reality and updates when reality changes (lessons 2 and 3).
- The folder documents the stable, not the volatile (lesson 5): the useful manual says where the main valve is (that doesn't move in years) and why the roof valve isn't touched in winter (a decision with its why). It doesn't say "today the living room is painted blue" —that changes, and a manual that tries to keep pace with what changes every month is always wrong—.
- The folder lets you operate without calling the previous owner (onboarding README, bus factor): the value of the manual is that you don't need the previous owner. You can operate the house without their phone number. If the manual also survives your own move and you leave it for the next person, the knowledge never depends on a single person (lessons 6 and 7).
The software system is the same. Mercado's payments module is the house; Elena is the previous owner who knows where each valve is. The module's question is: when Elena moves out, did she leave the team the folder —the manual that lets them operate payments without calling her— or is the team going to discover payments the hard way, wire by wire, decision by decision? This module trains you to write that folder, and —most important— to write the one that survives, not the one that rots in a drawer.
Worked example: Mercado's bus factor, and how the doc raises it
Let's start by putting a number on the risk we're talking about: the bus factor. The name comes from a brutal question —"how many people on the team would have to be hit by a bus for the project not to be able to continue?"—. In its useful form, a module's bus factor is how many people would have to leave for that module to be orphaned: with no one who knows how to maintain it. A module known by three people has bus factor 3 (all three would have to leave); one known by a single person has bus factor 1 —and that's the dangerous one, because a single departure leaves it ownerless—. The system's bus factor is the minimum among its modules: the weakest link sets it.
Let's compute it over Mercado's knowledge map, and then see what happens to it when we document the stable part of the weakest module:
# Bus factor: how many people would have to leave for a module to be
# ORPHANED (no one who knows how to maintain it). A module's bus factor is the
# number of people who know it today; the SYSTEM's is the minimum among modules:
# the weakest link. A module with bus factor 1 is a single point of failure:
# if that single person leaves, the module is left ownerless.
OWNERSHIP = {
# module -> people who can maintain it today
"catalog": ["Ana", "Beto", "Caro"],
"orders": ["Beto", "Diego"],
"payments": ["Elena"],
"shipping": ["Diego", "Caro"],
"platform": ["Ana", "Elena", "Beto"],
}
def bus_factor(module, doc=False):
# A STABLE doc of the module (its boundaries and decisions) acts as a
# "knower who never leaves": it adds 1 to the bus factor.
return len(OWNERSHIP[module]) + (1 if doc else 0)
print(f"{'module':<10}{'knowers':>13}{'bus factor':>12}{'status':>25}")
print("-" * 60)
for m in OWNERSHIP:
bf = bus_factor(m)
status = "SINGLE POINT OF FAILURE" if bf == 1 else "ok"
print(f"{m:<10}{len(OWNERSHIP[m]):>13}{bf:>12}{status:>25}")
print("-" * 60)
system_bf = min(bus_factor(m) for m in OWNERSHIP)
weakest = min(OWNERSHIP, key=lambda m: bus_factor(m))
print(f"SYSTEM bus factor: {system_bf} (set by the weakest module: {weakest})")
print()
print("We document 'payments' (its boundaries and decisions: the STABLE part):")
bf_before = bus_factor("payments")
bf_after = bus_factor("payments", doc=True)
print(f" payments: bus factor {bf_before} -> {bf_after}")
new_system_bf = min(bus_factor(m, doc=(m == "payments")) for m in OWNERSHIP)
print(f" SYSTEM bus factor: {system_bf} -> {new_system_bf}")
print("The doc doesn't replace the person, but it stops being the ONLY insurance:")
print("payments is no longer orphaned if Elena leaves.")What to expect. Running the file, the output is exactly this:
module knowers bus factor status
------------------------------------------------------------
catalog 3 3 ok
orders 2 2 ok
payments 1 1 SINGLE POINT OF FAILURE
shipping 2 2 ok
platform 3 3 ok
------------------------------------------------------------
SYSTEM bus factor: 1 (set by the weakest module: payments)
We document 'payments' (its boundaries and decisions: the STABLE part):
payments: bus factor 1 -> 2
SYSTEM bus factor: 1 -> 2
The doc doesn't replace the person, but it stops being the ONLY insurance:
payments is no longer orphaned if Elena leaves.
Read the table slowly, because it contains the whole argument of the module.
First, the diagnosis. Four of the five modules are healthy: catalog and platform with bus factor 3, orders and shipping with 2. But payments has bus factor 1, and the table marks it: SINGLE POINT OF FAILURE. And here's the scary detail: the system's bus factor isn't the average of the modules nor that of the strongest —it's that of the weakest—. Even though four of five modules are well accompanied, the whole system has bus factor 1, because it's enough for one person (Elena) to leave for one critical module (payments) to be orphaned. The system is as resilient as its weakest link, and Mercado's weakest link is a single head.
Second, the cure. We document the stable part of payments —not every volatile detail, but its boundaries and its decisions: why it's separated, what contracts it exposes, what business rules govern it—. That doc acts as one more knower, one that never leaves: any new person can read it and get up to speed. Payments' bus factor rises from 1 to 2, and with that the system's bus factor rises from 1 to 2. With a single act of documentation —the cheapest possible, because we document what doesn't change— we eliminate the single point of failure of the whole system.
Notice the program's final line, because it avoids an important misunderstanding: "the doc doesn't replace the person, but it stops being the only insurance". Documenting payments doesn't make Elena dispensable or replace her as an expert —Elena is still the one who knows the module best and who evolves it—. What the doc does is make her knowledge stop dying with her departure. Before, Elena was the only insurance against losing payments; now there are two: Elena and the doc of the stable part. If Elena leaves, the module isn't orphaned —it's left with a manual—. That's exactly the role of documentation that survives: not to substitute for people, but to prevent the system from depending on one particular person never leaving.
And notice something about the cost: we raised the bus factor by documenting the stable. If we had tried to raise it by documenting every volatile detail of payments —every function, every endpoint, every configuration value—, that doc would rot in weeks (payments changes those details often) and would go back to being worth 1. Documenting the stable is cheap to maintain and cheap for raising the bus factor, because the stable, by definition, doesn't change much. That's the connection between the bus factor (lesson 7) and the stable-vs-volatile rule (lesson 5), and that's why the module teaches them together.
The six pieces of the discipline
That example touched, without developing it, the module's thesis. Each lesson installs a piece of the discipline of documenting so that the knowledge survives. It's worth seeing them together, because they're the backbone of the seven lessons that follow.
1. Living documentation: why doc rots and what keeps it alive (lesson 2). The first piece: understanding why most documentation fails —it disconnects from the code and rots— and what it means for it to be alive: glued to the code, updated in the same change that would make it obsolete. It measures the trust chasm: when accuracy falls below a threshold, the whole doc is worth zero even if part is still correct.
2. Docs-as-code: doc in the repo, reviewed in PRs (lesson 3). The concrete practice that forces proximity: writing the doc in Markdown/PlantUML, versioning it alongside the code, reviewing it in the same PRs and validating it in CI. The lesson runs a validator that detects out-of-sync doc and breaks the build, turning "the doc rotted" from an invisible problem into a red test.
3. The C4 + ADR + arc42 system (lesson 4). Documentation that survives isn't a loose piece, it's a system: C4 shows the structure, the ADR keeps the why, and arc42 is the skeleton that organizes them and covers what's missing. The lesson measures the coverage of each piece alone (insufficient) against the combo (complete).
4. Document the stable, not the volatile (lesson 5). The rule that saves the doc from oblivion: document what changes little (the boundaries, the decisions) and not what changes every week (the endpoint list, the signatures). The lesson measures the ROI: the volatile costs more than it yields and becomes obsolete before it's read.
5. The README that onboards (lesson 6). The new dev's first contact: what the system does, how to run it, where the pieces are. The lesson measures the onboarding cost —the time to the first useful commit— with and without a README.
6. Bus factor and knowledge sharing (lesson 7). The heart: not depending on a single head. The lesson simulates who leaves and what's orphaned, and compares the insurances for raising the bus factor —the doc of the stable turns out the cheapest—.
Keep this map; it's the module's route:
Discipline piece Lesson The idea in one phrase
──────────────────────────────────── ──────── ─────────────────────────────────────
Living documentation L2 live doc lives glued to the code
Docs-as-code L3 the doc in the repo, a test that breaks
The C4 + ADR + arc42 system L4 three pieces, one doc system
Document the stable, not the volatile L5 document what doesn't change
The README that onboards L6 the first useful commit in hours
Bus factor and knowledge sharing L7 don't depend on a single head
──────────────────────────────────── ──────── ─────────────────────────────────────
Make Mercado's doc survive L8 the mini-project, executed
The map: where this module is in the guide and in the ecosystem
This module is the guide's second-to-last, and it closes the arc of the craft with the dimension of knowledge that endures. This is how it connects with the rest:
flowchart TD
M1["M1 · What an architect really does"]
M2["M2 · Conway's law"]
M3["M3 · Communicating architecture (C4)"]
M4["M4 · Technical leadership without authority"]
M5["M5 · Stakeholders and quality attributes"]
M6["M6 · Designing for change"]
M7["M7 · Documentation that survives<br/>(the knowledge that endures)"]
M8["M8 · Project: be Mercado's architect<br/>facing a change"]
M1 --> M2 --> M3 --> M4 --> M5 --> M6 --> M7 --> M8
Read it like this: in modules 1 to 6 you installed the role, the org↔system dynamic, the communication, the leadership, the translation of goals into attributes, and the stance toward change. Here, in M7, you add the dimension that makes all of that endure: the knowledge you produced —the decisions, the boundaries, the why— has to survive time and the turnover of people, or it's lost. In M8 you'll do the whole journey as Mercado's architect facing a real change, and documentation that survives will be part of what you deliver.
And the frontier with the rest of the ecosystem, which must be respected carefully. C4 —how to draw each level, which diagram for which audience— is module 3 of this guide; we don't re-teach it, we use it as a piece of the doc system. The ADR —how it's written, how a decision is classified, the mechanics— is the sister guide architecture-decisions-and-tradeoffs; we don't re-teach it either, we use it as the record of the why that survives. When in lesson 4 we talk about the "C4 + ADR + arc42 combo", we're not going to teach how to draw a Container or write an ADR (you already know that); we're going to teach how those pieces assemble into a system that lasts —and what arc42 adds so no gaps remain—. The usual distinction in this guide: the tools versus the craft of keeping them alive.
Common mistakes
These three mistakes are the three ways of failing at knowledge survival that the whole module fights. They appear here in summary form; each lesson opens one in depth.
The wiki that rots (documenting far from the code). What happens: the team writes documentation in a wiki disconnected from the code —Confluence, Notion, a Docs folder—, updates it once, and then the code keeps changing while the wiki stays still. In a few months the wiki is so out of sync that no one trusts it, and everyone goes back to asking the person who does know: the doc exists but is useless. Why it happens: writing the doc far from the code is more comfortable in the moment (it doesn't require touching the repo), but it breaks the only mechanism that keeps it alive —updating it in the same change that makes it obsolete—. How to spot it: if your doc lives in a system separate from the code, if no one opens it to work, or if the answer to "is this documented?" is "yes, but it's surely out of date", your wiki is rotting. How to fix it: move the doc to the repo, alongside the code, and review it in the same PRs —docs-as-code—, so that proximity forces it to stay alive. Lesson 2 measures the chasm: a wiki at 20% accuracy is worth zero, because no one trusts it.
Documenting the volatile too much and the stable too little. What happens: the team, with good intentions, tries to document everything —every function, every endpoint, every configuration value—, and since those details change all the time, the doc becomes obsolete in weeks; meanwhile, what would really survive —the decisions, the boundaries, the why— goes undocumented because there wasn't enough time. Why it happens: "documenting well" is confused with "documenting a lot", and the volatile is the most tempting to document because it's the most concrete and visible. How to spot it: if your doc describes function signatures or endpoint lists that change every sprint, but doesn't explain why payments is separated or what its boundaries are, you're documenting the volatile and forgetting the stable. How to fix it: document the stable (decisions and boundaries, which change little) and leave the volatile to the code or to automatic generation. Lesson 5 measures it: the volatile has negative ROI —it costs more to maintain than it yields—.
The knowledge in a single head (bus factor 1). What happens: a critical module is understood by a single person, and the team accepts it as normal —"ask Elena, she knows payments"— until the day that person leaves (on vacation, to another team, from the company) and the module is orphaned: no one knows why it's built the way it is or how to touch it without breaking it. Why it happens: it's comfortable. While the person is there, having the knowledge concentrated in them is efficient —no need to document anything, you just ask them—; the cost only appears when they leave, and by then it's too late. How to spot it: if there are modules "only so-and-so understands", if the team panics when that person goes on vacation, or if a module has bus factor 1, you have knowledge in a single head. How to fix it: raise the bus factor by documenting the stable part of those modules —the cheapest insurance— and complement with pairing or rotation for the live knowledge. Lesson 7 measures it: documenting the stable is 7.5 times cheaper than training a second human owner, and it eliminates the single point of failure.
Exercises
Exercise 1 — The system's bus factor. Mercado's knowledge map has four modules with bus factor 2 or 3 and one (payments) with bus factor 1. A manager looks at that and says: "the system is well documented, four of five modules have backup; the system's bus factor is good". Using the example's definition, explain why the manager is wrong, and what the system's bus factor really is.
See solution
The manager is wrong because they average (or look at the majority) when the system's bus factor isn't an average: it's the minimum among the modules, because the system is as resilient as its weakest link. Four of five modules having bus factor 2 or 3 doesn't help if the fifth —payments, and the one that charges the money— has bus factor 1: it's enough for one person (Elena) to leave for that critical module to be orphaned, and with it, the system can't keep operating with confidence. Mercado's system bus factor is 1, not "good". The manager's mistake is one of aggregation: they believe the whole's health is the average of the parts, when in fact it's set by the weakest part.
The practical consequence: to raise the system's bus factor you shouldn't work on the modules that are already fine (raising catalog from 3 to 4 changes nothing), but on the bottleneck —payments—. Documenting the stable part of payments raises its bus factor from 1 to 2, and with that the whole system's from 1 to 2. The craft's rule: to improve the system's bus factor, always attack the weakest module, not the average.
Exercise 2 — The three layers of the manual. The analogy of the manual the previous owner left you had three layers: (a) that the manual exists and is true, (b) that it documents the stable and not the volatile, (c) that it lets you operate without calling the previous owner. Translate each layer into a concrete problem of Mercado's payments module, and say which module lesson works on it.
See solution
(a) That the manual exists and is true → living documentation / docs-as-code (lessons 2 and 3). The concrete problem: a payments doc that says "it charges with provider X by direct write" is useless when it's actually been migrated to a queue and another provider —that doc not only doesn't help, it misleads the new dev, like the manual that says the heater is electric when it's gas—. The payments doc has to be synchronized with the real code and update when payments changes; that's achieved by keeping it glued to the code (living) and in the repo reviewed in PRs (docs-as-code).
(b) That it documents the stable and not the volatile → document the stable (lesson 5). The concrete problem: if the payments doc tries to list every endpoint and every configuration value (volatile), it will become obsolete in weeks; what it should document is the stable —why payments is separated from the core, what contracts it exposes, what business rules govern it—, which is what doesn't change and what a new dev really needs, just as the manual says where the main valve is (stable) and not what color the living room is painted today (volatile).
(c) That it lets you operate without calling the previous owner → onboarding README and bus factor (lessons 6 and 7). The concrete problem: the value of the payments doc is that a new dev can understand and touch the module without calling Elena. If every doubt about payments ends in "ask Elena", the doc didn't do its job and the bus factor is still 1. The doc that survives is the one that makes the call to the previous owner unnecessary —and thus the knowledge stops depending on a single head—.
Exercise 3 — Cheap because stable. In the example, we raised payments' bus factor by documenting the stable (its boundaries and decisions), not every detail. Explain why documenting the stable is at once cheap to maintain and effective for raising the bus factor, and what would happen if instead we tried to raise the bus factor by documenting every volatile detail of payments.
See solution
Documenting the stable is cheap to maintain by definition: the stable is what changes little —why payments is separated, what boundaries it has, what decisions hold it up don't change release to release—, so the doc of the stable barely requires updates and stays true for years with little effort. And it's effective for raising the bus factor because what a new dev needs so as not to orphan the module isn't the list of every function (that they read from the code), but the mental map: why it's built this way, where the boundaries are, what decisions they shouldn't undo without understanding the why. That mental map is exactly the stable, and it's what acts as "the knower who never leaves".
If instead we tried to raise the bus factor by documenting every volatile detail of payments —every endpoint, every signature, every configuration value—, two bad things would happen at once. First, that doc would rot in weeks, because payments changes those details often and no one would manage to keep it synchronized; before long it would be out of date, no one would trust it, and the bus factor would go back to 1 (a doc that's not trusted is worth zero, as we'll see in lesson 2). Second, we would have spent an enormous effort on what survives least and matters least for the mental map, probably leaving the stable —which does count— undocumented. The result: a lot of work, rotted doc, bus factor unimproved. That's why the rule —document the stable, not the volatile— isn't only about efficiency: it's what makes the doc survive and the bus factor stay up.
Summary and next step
In this lesson you installed the thesis that sustains the whole module: most documentation doesn't survive —it rots in a disconnected wiki— and documenting well isn't writing a lot, but writing what endures. You saw the Mercado case from the knowledge: the map of who knows what hides a single point of failure no diagram shows —payments is maintained by a single person, Elena, bus factor 1—. You measured it: the system's bus factor is set by the weakest module, so even though four of five modules are well accompanied, the whole system has bus factor 1; and documenting the stable part of payments raises it from 1 to 2, eliminating the single point of failure with the cheapest possible act of documentation. With the analogy of the manual the previous owner left you, you separated the three layers of the doc that survives: that it exists and is true, that it documents the stable, and that it lets you operate without calling the previous owner.
Before moving on you should be able to: explain why the system's bus factor is the minimum (not the average) of its modules; translate the three layers of the manual into concrete payments problems; and argue why documenting the stable is at once cheap to maintain and effective for raising the bus factor.
Lesson 2 takes the first piece of the discipline and develops it in depth: living documentation —why doc rots and what keeps it alive—. You'll see, with numbers, why a wiki disconnected from the code drifts out of sync until no one trusts it, and execute the trust chasm: the moment when accuracy falls below a threshold and the whole doc is worth zero, even if part is still correct. With that you'll understand why the only doc that survives is the one that lives glued to the code —and why the wiki's comfort is a trap—.
Resources
- Cyrille Martraire, Living Documentation: Continuous Knowledge Sharing by Design (Addison-Wesley, 2019) — the module's central book. Its thesis is exactly this guide's: documentation that survives is the one that lives glued to the code and the decisions, not the one written apart that rots. In English.
- arc42.org — the architecture-documentation template (Gernot Starke and Peter Hruschka) that lesson 4 uses as the skeleton of the doc system. Twelve sections that organize C4, the ADRs and what's missing (quality, constraints, risks). In English and German.
- Simon Brown — The C4 model (c4model.com) — C4 as a system of diagrams by level. In this guide it was taught how to draw it in module 3; here it's used as a piece of documentation that survives. In English.
- Michael Nygard — "Documenting Architecture Decisions" (2011) and adr.github.io — the ADR as the why that travels through time. Its mechanics are the sister guide
architecture-decisions; here the ADR is the stable record that survives the turnover of people. In English. - Write the Docs — the community and the docs-as-code idea — the practice of treating documentation as code: in the repo, in plain text, reviewed in PRs, validated in CI. The basis of lesson 3. In English.
- Martin Fowler — Software Architecture Guide — the hub for going deeper into why architecture matters and how to communicate and document it; a good bridge to the rest of the ecosystem. In English.