Documentation Is Not What You Think

Tacit vs. Explicit Knowledge

Documentation Is Not What You Think

Why the most detailed tickets are often just maps of cities that have already burned down.

I once tried to replace my entire personality with a wiki. This was a mistake. I was leading a small team of emoji localization specialists. We were working across four time zones. I thought the friction was just a lack of data. I believed every misunderstanding was a failure of the manual.

So I spent building the ultimate repository. It had rules for every possible interaction. It defined the exact emotional weight of a “thumbs up” in Jakarta. It explained why a “sparkle” emoji in Paris felt sarcastic. I told my team to stop calling me. I told them to read the wiki instead.

🧱

The Knowledge Wall

I thought I had built a bridge. I had actually built a wall. I was wrong. I was deeply, foolishly wrong.

The wall I built was made of explicit knowledge. But the team needed the tacit kind. They needed the “why” that only lives in a sigh. They needed the context that hides in a pause. My wiki could not capture the way my voice trailed off. It could not explain the specific urgency of a Tuesday.

You cannot put “vibes” into a bulleted list. My toe currently hurts very much. I just stubbed it on a mahogany coffee table. The table is solid and heavy. It does not care about my wiki. It does not care about my feelings. It is a physical reality that demands attention.

🦶

My pain is also a physical reality. This pain is making me very blunt. It is making me think about Elena. She is a developer I worked with years ago. Elena was the queen of the thorough handoff. She did not believe in “vibes.” She believed in the ticket.

The Masterpiece of Detail

Elena once wrote the longest ticket in company history. It was for the engineering team in Seoul. It was meant to transfer a complex billing migration. The ticket was a masterpiece of detail. It contained 142 individual steps. It had screenshots with red arrows. It had links to legacy codebases.

Explicit Steps

142

Tacit Context

0

The “Knowledge Imbalance”: Elena spent polishing 142 steps, but the “fear” of the 2019 bug was missing.

Elena felt a sense of immense safety. She thought the Seoul team had everything they needed. She was wrong too. What Elena could not put in the ticket was Step Four. Well, Step Four was in the ticket. But the “why” of Step Four was missing.

In the ticket, Step Four was a simple command. It told the team to clear a specific cache. To a developer in Seoul, this looked like bloat. It looked like an old habit from a dead system. They were smart engineers. They wanted to optimize the process. They looked at Step Four and saw a ghost. They decided to delete it.

“The billing system crashed instantly. The bug that Step Four was meant to kill had returned. It was a bug that everyone had forgotten.”

– The Tacit Memory of Outage

Everyone except Elena. She had lived through that outage. She remembered the heat of the server room. She remembered the smell of burnt coffee. That memory was her tacit knowledge. It was the “feel” of the code. She could write the instruction in a ticket. She could not write the fear into the ticket.

The handoff failed because the language gap was a filter. It let the “what” through. It caught the “why” and threw it away. This is the central problem of global work. We think we are communicating. We are actually just exchanging receipts. We are trading the maps but losing the terrain.

Three Aspects a Ticket Kills:

  • The History: Why we tried the other way first.
  • The Friction: The parts of the code that feel “brittle.”
  • The Grace: The small workarounds that keep users happy.

I used to think more words meant more clarity. This was my second big mistake. I thought a 4,000-word document was better than a 400-word one. I was wrong. A long document is just a larger haystack. The needle of meaning is still hidden inside.

$9,840

Financial Disaster

31%

Lead Time Lost

The result of a 20-page brief where the designer only read the first three pages and guessed the rest.

If we had talked for , we would have saved it all. The problem is the “explicit trap.” We think if we name it, we own it. But tacit knowledge is like riding a bicycle. You can read a book about balance. You can study the physics of a wheel.

You can memorize the anatomy of a pedal. But you still do not know how to ride. You only know how to ride when you feel the tilt. You know it when your inner ear talks to your legs. That conversation is internal. It is fast. It is messy. It is impossible to write down in a Jira ticket.

The Book (Explicit)

  • Physics of wheels
  • Pedal anatomy
  • Torque specifications

The Ride (Tacit)

  • Inner ear balance
  • Feeling the tilt
  • Subconscious leg response

When you hand off to an overseas team, you sever the ear. You send the book on physics. You expect them to ride the bike perfectly. Then you are shocked when they fall over. You blame their skills. You blame their culture. You never blame the ticket.

I am limping now. The mahogany table has won this round. It reminds me that some things must be felt to be understood. You cannot “read” a stubbed toe. You can only experience it. Language is often the barrier to this experience. When I work with teams in different countries, I feel the gap.

I see the Seoul team staring at Elena’s Step Four. I see them thinking it is a mistake. I want to jump into the screen. I want to tell them about the outage. I want them to feel the heat of the server room. But I cannot do that through a comment box.

A comment box is a cold place. It strips away the tone of voice. It removes the urgency from the eyes.

It turns a plea into a demand. This is where the real work dies. It dies in the translation of intent. We need a way to keep the conversation alive. We need to talk, not just text. We need to hear the hesitation in a colleague’s voice. We need to see the “sparkle” emoji and know if it is a joke.

The Transync AI Bridge

This is why tools that facilitate real-time understanding are vital. When you can actually speak to each other, the tacit flows. The “why” hitches a ride on the “what.” You can explain Step Four in .

You can say, “Hey, this looks weird, but don’t touch it.” You can describe the ghost of . This is the power of Transync AI in a global stack. It allows the conversation to happen across the language gap.

It keeps the “feel” of the project intact. It prevents the 142-step ticket from becoming a suicide note for the product. I once hired a translator for a meeting with a client. It was a disaster. The translator got the words right. He got the meaning wrong.

The translator translated “I am concerned” as “I am angry.” The client walked out. We lost a contract worth thousands. I realized then that translation is not about words. It is about the weight of those words. If you don’t have the weight, you don’t have the truth.

“Documentation captures only the legible layer. The legible layer is the smallest part of the job. The rest is the ‘dark matter’ of work. It is the stuff we know but cannot say.”

– Reflection on the Legible Layer

Daniel J.-M. once told me about an emoji crisis. He is an emoji localization specialist. He saw a team use a “folded hands” emoji. In one culture, it meant “please.” In another, it meant “high five.” In a third, it meant “prayer.”

🙏

1 Glyph

3+ Meanings

Tacit Context

The ticket said “Use the folded hands emoji.” The team followed the ticket. The users were offended. The ticket was technically perfect. The ticket was a total failure. Daniel had to explain the “vibe” of the hands. He had to show them the different meanings in a live call.

He had to use his hands to show the gesture. That is tacit knowledge in action. It is the movement of the body. It is the inflection of the voice. You cannot put that in a PDF. You can only put it in a conversation. And if you cannot have the conversation because of a language barrier, you are flying blind.

I used to be angry at my teams for missing the point. I thought they weren’t paying attention. I was wrong. I was the one not paying attention. I was ignoring the reality of human connection. I was trying to turn my coworkers into processors. But processors don’t understand Step Four. Only people understand Step Four.

The language gap is a server of context. It cuts the line between the “why” and the “how.”

We spend millions on project management software. We spend pennies on actually understanding each other. We buy Jira licenses like they are magic charms. We think a board full of cards is a team. It is not. It is just a pile of cards. A team is the air between the cards.

I am sitting down now. My toe is throbbing. I am looking at the mahogany table. It is a very well-documented table. I know its height. I know its weight. I know its material. None of that documentation helped me avoid hitting it. I needed to see it. I needed to feel its presence in the room.

The mahogany table is a silent witness to every ticket that failed to speak.

If we want to work globally, we have to stop hiding behind tickets. We have to stop pretending that a detailed handoff is enough. We have to find ways to let the tacit knowledge cross the ocean. We need to hear the Seoul team’s questions. We need to answer them in real time. We need to let the “why” survive the trip.

Otherwise, we are just building more walls. We are just stubbing our toes on the same mahogany tables. Documentation is a safety net, not a bridge. It will catch you if you fall. It will not get you to the other side. Only conversation can do that.

Only the messy, fast, intuitive exchange of ideas can keep a project alive. We need to invest in the “between.” We need to value the pause and the sigh as much as the bullet point. We need to realize that the most important part of the work is the part we can’t write down.

I am going to put some ice on my toe now. I am also going to delete my old wiki. I am going to call my team. I am going to ask them how they feel. I am going to listen to the “why” behind their “what.” It won’t be as tidy as a spreadsheet. It won’t be as organized as a Jira board.

But it will be real. And in the end, the real stuff is the only thing that actually works. We should stop pretending that a ticket is the truth. The truth is much noisier than that. The truth is a conversation that never quite ends. Transync AI