Tribal knowledge is the part of the job nobody writes down. It leaves when the person leaves. Lately it goes without anyone noticing, because an assistant stands ready to answer instead.
The room had a whiteboard with somebody else’s sprint plan on it, three weeks old. Nobody had wanted to be the one to erase it. There were six of us at the table. The billing system had been rounding a few cents differently on large invoices, and a customer had asked.
They had everything a team is supposed to have. The code was in version control, with comments. The tests passed. On a laptop at the end of the table, an assistant could explain any function in seconds.
Nobody in that room could tell me whether they were allowed to change it.
The Rounding Rule
The rule was four lines long. Above a certain invoice amount, the system rounded a different way. The developer who wrote it had left eight months earlier, in the ordinary way. There was a cake, a card, and a short speech about missing everyone.
The assistant described those four lines accurately. It offered a cleaner version, which was in fact cleaner.
What it could not tell us was why the lines existed. Perhaps a regulator required it. Perhaps somebody had promised it to one large customer, in a negotiation nobody at the table had attended. Perhaps it worked around a system that was switched off in 2021.
Or perhaps it was a mistake that stayed harmless for six years. That happens more than anyone admits.
Four explanations, one piece of code, and each led somewhere different. Delete it, or document it and never touch it, or ask legal. The engineering lead said what everyone was thinking. They would leave it alone and add a note.
The customer was told the invoice was correct. That was true. Nobody in the company could say why it was true.
That is how a system becomes haunted. Not by bad code, but by code that works and nobody can account for.
Scars and Accidents
Every mature system I have worked on has these small strange places. A retry loop that waits exactly forty seconds. A customer ID hard coded into a WHERE clause. A nightly job that runs at 3:40 instead of a sensible round number.
Some of them are scars. Somebody learned something at two in the morning and left protection behind for the rest of us. Others are accidents nobody ever removed.
From the outside the two look identical, and you cannot tell by reading. The laptop at the end of the table had read every line of it. Reading was never the part that mattered.
The Text Message Era
For twenty years we handled this badly, and it worked anyway.
Somebody new would read the code, get confused, and text the person who had left. “What is the forty second retry for?”
The reply came back between meetings at the new job, curt and entirely sufficient. “The provider used to time out at thirty seconds. Support told us to go higher. Ask them first.”
Nobody wrote that down, so the new person became the next keeper of it. That is how tribal knowledge stays tribal. It also survived, which is more than the wiki managed.
You could argue this was never a handover plan, and you would be right. It ran on goodwill and a phone number that still worked. I would rather have a real process. We have never had one, and we are now losing the thing that covered for us.
What Changed
The new person does not text anybody now. There is no need. The question goes to the assistant and the answer arrives at once. It is a good answer about what the code does.
The tab closes. The person feels caught up. The one human who knew why was not consulted, and nothing in the experience suggested that anyone was missing.
This is the part worth sitting with. The old failure was loud, because you had to admit confusion to a stranger and wait for a reply. The new failure is quiet and rather pleasant, and it feels like competence.
Four Lines
The answer is not more documentation. Every company has the wiki already, three hundred pages, last edited in 2019. The author has since moved to Portugal.
What is worth writing is smaller. When you make a decision, write four lines: the choice, the alternative, the reason, and what would make this wrong.
The fourth line is the one nobody writes. It is also the only one that helps the next person. It names the conditions under which they can undo your work.
Without it they do what that room did. They leave it alone and add a note.
Keep the lines in the repository, beside the code they explain. Then they travel with the thing they describe, and somebody finds them while already looking in the right place.
The log catches what you decide from now on. The rounding rule was already in there, and for that you need an hour with a person.
The Hour Nobody Books
When people resign, we ask them to document their work. They write down what the system does, which was never the missing part, and everyone agrees the document is thorough.
Book a different hour. Turn on a recorder and ask what would break if a new person did the obvious thing. What looks wrong in here and is right? What did you try that failed, and what are you afraid somebody will change?
Ask which customer has an arrangement that appears in no document. Ask what happens in December that happens in no other month. An hour of that beats anything they will type.
Where the Tool Earns Its Keep
None of this is an argument against the laptop at the end of the table. I use it on every unfamiliar system I am handed. It gives you the best first week you have ever had.
It maps the place in an afternoon. It finds every use of a field and follows a value through a dozen services. Then it explains all of that to somebody who arrived on Monday, which used to take a month of reading.
It’s a good map of what’s there. The map you need in week one shows what everybody is afraid of, and that one has never been drawn.
So start the log this week, four lines at a time. When somebody asks the assistant why the code is like that, have them ask the longest serving person too. The answer could be worse. The question is the last chance you get.
If you have a system nobody understands anymore, that’s the sort of thing I get called about. You can see how I work with teams on my consulting page.
I wrote about the larger version of this in Competence Debt. It is an essay about the understanding a team never builds when a tool does the work. It is one of thirty essays in my book AI: Nobody’s in There. But we’re still in here. All of them are free to read online, and the paperback is on Amazon.
The code is not the knowledge, it is the leftovers of a decision nobody wrote down.
Published by Pinal Dave on SQLAuthority. More of my work at pinaldave.com.
Discover more from SQL Authority with Pinal Dave
Subscribe to get the latest posts sent to your email.
