What your organization is quietly forgetting how to explain
Why understanding used to arrive free, why better documentation does not replace it, and how to measure what you have left in an hour.
Your organization understood its systems because people built them. That has stopped.
Nobody was ever assigned to understand your systems. It came attached to the work: you cannot build a thing without learning how it fails. Automate the building and the side effect stops arriving, and because nobody was assigned it, nobody is positioned to report that it has.
This volume is twelve short steps on what that costs, why every instrument you have says you are fine, and what it takes to produce understanding on purpose. It assumes you have read nothing else in this series.
The one page to read if you read one
The deficit is invisible for as long as normal operation lasts, because knowing where to look is genuinely sufficient for normal operation. It becomes visible during an incident, when the only thing that helps is somebody who can explain the system.
Which means the only instrument that measures this is an incident — unscheduled, under load, in front of people. The most useful page here is the one that shows you how to take the measurement at a better time, on purpose, in an hour.
What you can do afterward
Write down what your organization knows as a list of names, and find the blank rows. Tell a documentation problem from a comprehension problem. Run a test that produces a number about your own team. And explain to your own leadership why this particular cost cannot be delegated downward.
The questions and the four practices that work are collected on one page you can print.
Every term this page uses
- byproduct
- Something produced as a side effect of doing something else, which nobody decided to make and so nobody maintains.
- comprehension
- Being able to work out what a system will do next, including in a situation nobody has written down.
- navigation
- Knowing where the answer is recorded. Cheaper than comprehension, and not a substitute for it.
- organizational memory
- What a company collectively knows, which in practice means which particular people know it.
- re-derivation
- Working something out again from scratch when you could have looked it up. The only known way to produce comprehension on purpose.
- tabletop
- A rehearsal: pose a failure that has not happened, and watch how people reason about it.
- time to first hypothesis
- How long somebody takes to offer a plausible explanation worth testing. The number step nine asks you to measure.
- attribution
- Being able to say which change or decision produced an outcome.
- load-bearing
- Something the work depends on, whether or not anybody has noticed that it does.
Taken as already known, and so not defined here: agent, model, system, incident, documentation. That list is a claim about who is reading, and it is printed so it can be argued with.