Docs > Communication

June 8, 2024 (11mo ago)

Archive

Humanity's progress hinges on one thing: the ability to preserve knowledge. Thousands of years ago, we were just like any other species, learning through direct experience and passing it down verbally. Your father taught you to hunt, your mother taught you to forage, and you passed that knowledge to your children. But what happened if you died too soon? Or if the knowledge wasn’t passed on clearly? It was lost forever, forcing the next generation to rediscover everything from scratch.

The invention of writing changed everything. For the first time, knowledge could outlive individuals, communities, and even civilizations. Writing made us efficient, scalable, and resilient. Without it, we’d still be stuck in the Stone Age. That same principle applies to modern organizations: if your knowledge isn’t documented, it might as well not exist.

Every undocumented meeting, call, or decision is like the burning of the Library of Alexandria all over again. Knowledge is lost, leaving your project weaker and more dependent on oral tradition. And oral tradition is a death sentence for scalability, clarity, and long-term success.

The Problem with Lost Knowledge

Think about how software projects are run today. Teams rely on constant "meetings" (more on this in another post), quick calls, and Slack messages to "communicate." But what happens when the people involved in those conversations leave? What happens when new developers join and have to piece together the context themselves? The knowledge is gone.

Or worse, it’s trapped in someone’s head. Knowledge hoarders, whether intentional or not, become bottlenecks. If they’re sick, busy, or quit, the entire project grinds to a halt. This is irresponsible and inefficient. Knowledge in software MUST be conserved, and the only way to do that is through documentation, correct documentation.

Why Documentation Beats Communication

Communication is fleeting. It relies on people being available, attentive, and cooperative at all times. Documentation, on the other hand, is permanent. It’s the written record of your system, your decisions, and your solutions. It doesn’t depend on memory, context, or the availability of specific individuals.

When your project is well-documented, anyone can step in, understand the system, and contribute without needing endless meetings or hand-holding. Documentation doesn't only save time, it also serves as ongoing insurance ensuring that your project isn't fragile.

No matter how good your team is, people leave. Platforms change. Requirements evolve. If you’re not documenting your work, you’re gambling with your project’s future.

Calls Are Not Documentation

How many times have you heard "Let’s hop on a quick call."? Calls are fine for brainstorming or emergencies, but they’re no substitute for documentation. Here’s why:

  • Calls don’t scale. The knowledge shared in a call is only accessible to the people who were there, while everyone else is out of luck. You can use tools to summarize the call, but that's not the same as having the documentation that's queryable.

  • Calls create dependency. If you have to explain something in a call, it means the information isn’t documented. That means the same question will come up again and again, wasting everyone’s time, and time is money.

  • Calls destroy continuity. Knowledge shared in a call often disappears the moment the call ends. Unless someone takes thorough notes (and let’s be honest, they rarely do), the information is effectively lost forever.

  • Good thinking isn’t instant. People need time to absorb, reflect, and articulate. You can’t freestyle clarity. Insight takes digestion. When you rely on calls, you interrupt the thinking loop: receive, hold, process, respond.

Instead of jumping on calls, solve the root problem. If something is unclear in the codebase, document it. If someone finds a bug in an open-source library, write about it on Stack Overflow or GitHub. If there’s missing context in the documentation, fix the documentation. Do not "secretly" do it.

The Goal: Autonomous Software Projects

The ultimate goal of any software project should be autonomy. A well-documented project doesn’t need constant explanations, meetings, or context-switching. It runs itself. New hires should be able to:

  • Join the project.

  • Read the context.

  • Start contributing. All on their own.

If your project can’t meet this standard, you’re doing it wrong. No one should have to ask endless questions or attend dozens of calls just to get started. The information they need should already exist.

The act of preserving context is a commitment to quality. It's ensuring that your work outlasts you, your team, and even your company. Every undocumented decision is a risk. Every undocumented process is a liability. And every undocumented call is a lost opportunity.

Preserve the knowledge. Make your project future-proof. Because at the end of the day, communication fades, but documentation lasts forever.

Subscribe to my newsletter. The extension of these thoughts and more.