How Knowledge Flows: Hallway or Document?

While I was working at an owner-run company, the most senior person on the team resigned. On his last day everyone said nice things, there was cake, and he left. Three weeks later a payment integration started behaving strangely: in one specific case, the system was deliberately sending the request a second time. The code was there, it worked, and it had worked that way for years. But nobody was left who knew why it had been written that way.

We argued about it for two days. Some people said “this is a bug, rip it out,” others said “he must have had a reason.” In the end we didn’t touch it — because nobody could carry the risk. That was the day it clicked for me: he had left the code behind and taken the reasoning with him.

Years later, in a corporate, I watched what looked like the exact opposite. We were discussing a topic for the third time in a meeting. Halfway through, someone said “this is already written up in the wiki” and dropped the link. It genuinely was. Written in 2023, sitting under the fourteenth heading of a forty-page page. Nobody had read it. The meeting ran a full hour anyway.

They look like two different failures. They aren’t. The root is the same: the reasoning behind the decision isn’t anywhere you can reach it at the moment you need it. In one case it lives inside a person’s head; in the other, inside a dead wiki. The outcome is identical: it isn’t there.

In the first post of this series I described four axes that separate companies; the second one was “how much is written down?” (corporate or owner-run?). This post digs into exactly that axis — not the technical side of it, the human side. Where knowledge sits, why it doesn’t get shared, and what happens when it doesn’t.

Whoever holds the knowledge holds the power — and that’s a risk for the company

Let’s be honest first, because nobody says this out loud: holding the knowledge really does buy you security.

If you’re the only one who understands that integration, the only one who remembers why that cron runs at three in the morning, the only one who can explain why that customer gets special treatment — you’re last on the layoff list. That’s leverage. Being indispensable is a survival strategy nobody teaches you and almost everybody discovers on their own.

And in the short term it works. The problem is the long term.

The indispensable person cannot be promoted. Because a promotion means taking you out of where you are — and if they take you out, nobody can fill the gap. The picture in your manager’s head is this: “If I pull this guy, that side collapses.” The sentence sounds like praise. In practice it means you’ve been nailed in place.

Hoarding knowledge is security in the short run and a ceiling in the long run. The thing that makes you un-fireable is the same thing that makes you un-promotable.

Why doesn’t anyone write it down?

There are two different reasons in the two company types, and both are cultural.

In an owner-run company, writing counts as “bureaucracy.” The moment you sit down to write something up, it’s near-certain someone will say “the job would’ve been done by the time you finished typing that.” Productivity there means visible output, and writing doesn’t produce visible output. But the real reason sits higher up: the owner himself doesn’t write. He gives decisions verbally, keeps the reasoning in his head, and phones in the correction that just occurred to him. Culture flows downhill. A team that writes under an owner who doesn’t only ever forms through one person’s stubbornness — and it ends when that person leaves.

In a corporate, things do get written — but the wrong thing gets written. A corporate loves writing; it has a template, a page, and an owner for the page. But what gets written is almost always the process: what was done, who approved it, which steps were followed. The “what we did” is there. The “why we did it” isn’t.

The gap shows up six months later. A process record gives you the trail of a decision, not its ground. Six months on, when someone asks “why did we do it this way?”, all you have is an approval chain — the constraint that forced the decision, the alternative that was ruled out and why, are written down nowhere. The result: nobody can question the decision. Questioning requires ground, and there is no ground. So bad decisions survive even though nobody is defending them.

”We’ll talk about it in the meeting” usually means “I’m not going to write it down”

A meeting is, in theory, a tool for transferring knowledge. In practice, it turns very easily into a tool for withholding it.

I’ve heard this line a lot: “We’ll talk about it in the meeting.” It sounds collaborative. Most of the time what it means is: I’m not going to write this down, I’ll say it out loud, and what I say out loud becomes the private knowledge of whoever’s in that room.

Unwritten knowledge is a privilege belonging to the people in the room. And who gets invited into the room is a decision — often not even a conscious one, just the reflex of “this is how we’ve always done it.” After a while the company splits into two classes: the people who are in the meetings and the people who aren’t. The ones who aren’t know what the work is; they don’t know why it is. And then they get told they “don’t take initiative.”

If a meeting doesn’t produce a three-sentence note, that meeting didn’t happen. I don’t say that as a rule, I say it as an observation: six months later, there is no measurable difference between a meeting with no notes and a meeting that never took place.

Writing on the inside is a career investment too

I’ve written before about the career return on writing for the outside world: blogging, talks, open source — being visible lets your ability speak on your behalf.

The same mechanism works inside the company, and almost nobody talks about it.

The person who writes regularly on the inside becomes, over time, the reference point for decisions. When someone new joins, what they read is what you wrote. When an argument breaks out, you’re the one who says “we discussed this before, it’s written up here.” Six months later, when a decision needs defending, you’re the only person holding any ground.

This isn’t the authority that comes with a title; it’s the authority that comes from accumulation. Nobody grants it to you and nobody can take it back. In the mentorship post I described something similar: growing someone else isn’t a sacrifice, it’s a multiplier. Writing is the same. What you’ve written keeps working when you’re not in the room — and the most valuable thing in a career is the thing that works while you sleep.

What to write: not the decision, the reasoning

If you’ve read this far and you’re asking “fine, but how?”, my answer is boringly simple.

Don’t write down the decision. Write down the reasoning.

“We chose X” is not a record; the code already says that. The record is this:

We chose X, because constraint Y applied. We ruled out Z, because W.

Three sentences. Five minutes. Where you write it doesn’t matter at all — a pull request description, a comment under the task, a message dropped in the team channel. The form isn’t what matters. Its existence is.

Here’s why that’s enough: what the person arriving six months from now needs isn’t your decision, it’s your constraint. If the constraint still holds, so does the decision; if the constraint is gone, the decision is open for debate. When you don’t write the constraint down, they’ll either preserve that decision blindly or tear it down blindly. Both are expensive.

If you want to build a deeper decision-record discipline — templates, versioning, a review flow — that’s a separate matter and it’s out of scope here. My claim in this post is narrower: even before you build that discipline, three sentences beat nothing by a wide margin. People usually write nothing because they can’t build the perfect system. That’s the most common and most unnecessary loss of all.

Question: How do I tell whether knowledge flows healthily in a company? Answer: Pick a decision at random and ask “why is this the way it is?” In a healthy place, the answer points to a document. In an unhealthy place, the answer points to a person — either “Ahmet knows” or “we discussed it in a meeting.” Both say the same thing: the knowledge belongs to some individuals, not to the institution.

Three desks

From the senior engineer’s desk. You believe that sharing what you know will lower your own value. It works the other way round: the person who shares becomes a multiplier, the person who hoards becomes a bottleneck. And bottlenecks don’t get promoted — they get kept in place, because they can’t be moved. Your constraint: this is only true where the sharing is seen. In a company where nobody notices what you wrote, and where you can be discarded comfortably once you’ve handed the knowledge over, this genuinely is exploitation — and that has to be said. Work out what type of company you’re in first, then open up.

From the manager’s desk. You want a single source of truth. But you can’t force the team to write; writing always comes second to the deadline, and deep down you know they’re right. Your constraint: the hour spent writing is the one hour that produces no visible output — and visible output is what’s being asked of you. If you want to defend that hour, you have to present it not as a favour but as the cost of a risk: “If these three people leave tomorrow, what do we lose?”

From the owner’s desk. Emptying out what’s in your head raises the value of the company. It makes it transferable, sellable, something you can take a holiday from. A company that lives in your head can never be bigger than you. Most owners only realise this when they try to sell: the first thing the other side asks is “what’s left if the founder walks away?”, and if the answer is “not much,” that’s where the price starts dropping. Your constraint: emptying out your head means emptying out some control with it. Every piece of reasoning you write down becomes something that can be argued with you about. That is genuinely frightening — and there’s no point asking “why does nobody write anything down?” while ignoring where the fear comes from.

Closing

Whether knowledge flows through the hallway or through a document isn’t an argument about tooling. It’s an argument about power.

Knowledge kept in someone’s head hands that person short-term security and writes the company a long-term debt. A dead wiki manages both at once: it protects neither the person nor the company.

I’ll suggest one thing for tomorrow. Take a decision you made today and write its reasoning down somewhere in three sentences. Don’t look for a template, don’t ask permission, don’t try to find the right place. Those three sentences will save somebody — possibly you — an hour, six months from now.