What is Tacit Knowledge? Why Developers Can't Document Everything

Apr 4, 2026

Stacks of books representing documented and undocumented knowledge

Purpose

Tacit knowledge is the undocumented understanding that experienced developers possess about critical production systems. It’s the “why” behind architectural decisions, hidden dependencies, and system quirks that can’t be easily written down or transferred.

The philosopher Michael Polanyi captured this perfectly in 1958: “We know more than we can tell.” This concept explains why experienced developers are valuable yet paradoxically vulnerable in today’s job market.

Here’s what the knowledge landscape looks like:

                    ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
                   ~    DOCUMENTED KNOWLEDGE    ~
                  ~   (10% - visible, codified)  ~
                 ~  ___________________________  ~
                ~ /                             \ ~
               ~  |  APIs, READMEs, Wikis        | ~
              ~   |  Code comments, Docs         |  ~
             ~    |  Procedure manuals           |   ~
            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           ~     ~     ~     ~     ~     ~     ~     ~
          ~      ~ TACIT KNOWLEDGE (90%) ~      ~
         ~       ~  (hidden, undocumented) ~    ~
        ~        ~___________________________~   ~
       ~         |                             | ~
      ~          | System quirks & workarounds |  ~
     ~           | Historical context          |   ~
    ~            | "Don't touch this" zones    |    ~
   ~             | Hidden dependencies         |     ~
  ~              | Decision rationale          |      ~
 ~               | Problem-solving intuition   |       ~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The invisible 90% makes experienced developers irreplaceable to their teams but doesn’t protect them from layoffs.

The Problem: Why Documentation Fails

I’ve watched countless organizations try to solve the “bus factor” problem through documentation initiatives. They create wikis, mandate code comments, write runbooks. Yet critical knowledge still disappears when key developers leave.

The fundamental issue: Tacit knowledge can’t be written down.

Explicit vs Tacit Knowledge

Explicit knowledge is factual, procedural, and documentable. Tacit knowledge is intuitive, contextual, and experiential.

# Explicit knowledge (documentable):
def process_payment(amount: float, user_id: str) -> PaymentResult:
    """Process a payment for a user.

    Args:
        amount: Payment amount in dollars
        user_id: Unique user identifier

    Returns:
        PaymentResult with status and transaction ID
    """
    return payment_service.charge(amount, user_id)

# Tacit knowledge (not documentable):
# "Always check if user_id starts with 'test_' in staging, but the
# staging detection logic fails 2% of the time due to a race condition
# in the config loader. Add a 100ms delay before checking or you'll
# get false positives. This cost us $50k in 2019 when we accidentally
# processed real payments against test accounts."

The function signature and basic logic are explicit. The quirk about staging detection, the race condition, the 100ms workaround, and the $50k incident—that’s tacit knowledge.

Critical Systems Accumulate Undocumented Knowledge

Every production system I’ve worked with has accumulated layers of tacit knowledge:

- Workarounds for bugs that "we'll fix later" (never fixed)
- Performance quirks requiring specific operation sequences
- Dependencies nobody documented because they seemed obvious
- "Don't touch this or everything breaks" zones
- Historical reasons for seemingly strange architectural decisions
- Informal communication channels for solving problems
- Unwritten conventions about code organization

The longer a system runs, the more tacit knowledge accumulates. Legacy systems are often the worst—not because the code is bad, but because the people who understood it have left.

The Bus Factor Problem

When developers with tacit knowledge leave:

IMMEDIATE IMPACT:
- Systems break unexpectedly
- Onboarding new developers takes months instead of weeks
- Critical bugs take weeks instead of days to fix
- Features delayed due to fear of breaking things

LONG-TERM IMPACT:
- Technical debt compounds as new devs avoid "danger zones"
- Architecture degrades as context is lost
- Production incidents increase
- Team velocity permanently reduced

A Reddit discussion on r/ExperiencedDevs asked: “What actually makes a developer hard to replace today?” The top answer (657 votes): “Knowing a lot of undocumented things for critical production systems.”

The Solution: Strategies for Managing Tacit Knowledge

You can’t document tacit knowledge directly. But you can create systems that capture, transfer, and preserve it indirectly.

Strategy 1: Pair Programming & Mob Programming

Direct collaboration transfers tacit knowledge through observation and shared experience:

WHAT TRANSFERS:
- Watching how experienced developers debug
- Hearing internal monologues during problem-solving
- Observing the "why" behind decisions in real-time
- Learning unwritten conventions through mimicry
- Absorbing system intuition through repeated exposure

WHY IT WORKS:
Tacit knowledge is rooted in action and context.
You can't write it down, but you can watch it happen.

When I pair with junior developers, they learn things no documentation could teach: how I approach unfamiliar code, what questions I ask when debugging, which warning signs trigger my concern.

Strategy 2: Architecture Decision Records (ADRs)

ADRs document the “why” behind decisions—the most critical form of tacit knowledge:

# ADR-042: Use PostgreSQL for session storage

## Status
Accepted

## Context
We considered Redis, Memcached, and PostgreSQL for session storage.

## Decision
Use PostgreSQL with a dedicated sessions table.

## Consequences
- Pros: ACID compliance, existing expertise, simpler stack
- Cons: Slightly slower than Redis, but negligible for our scale
- **Critical:** Our PostgreSQL driver has a bug with prepared statements
  on connection pool refresh. See workaround in session_store.py:L47.
  This was discovered after a production incident in March 2024.

## Related Decisions
- ADR-038: Database connection pooling strategy
- ADR-051: Session timeout configuration

The “Critical” section captures tacit knowledge that would otherwise disappear. New developers reading this ADR immediately understand the quirk, not just the decision.

Strategy 3: Rotation & Cross-Training

Knowledge silos form when developers own specific system areas exclusively:

ROTATION:
- Rotate developers across different system components quarterly
- Create "code archaeology" sessions to explore legacy systems
- Assign on-call duties across team members (not just experts)

KNOWLEDGE TRANSFER SESSIONS:
- Schedule structured transfers before team changes
- Create "shadow" programs for critical systems
- Document the debugging process, not just solutions

I’ve seen teams eliminate bus factor by ensuring every critical system has at least two people who understand it deeply.

Strategy 4: Documentation Culture

Documentation fails when it’s treated as a separate activity. It succeeds when it’s part of the workflow:

CODE COMMENTS:
- Comment the "why," not the "what"
- Include historical context for strange code
- Document workarounds with their origin dates

RUNBOOKS:
- Include troubleshooting guides with real examples
- Document false positives and expected quirks
- Record the debugging process, not just the solution

WORKFLOW INTEGRATION:
- ADR required for architectural decisions
- Runbook required for new operational procedures
- Code review must check for "why" documentation

Strategy 5: Mentorship Programs

Structured mentorship transfers tacit knowledge systematically:

FIRST 90 DAYS:
- Pair new developer with experienced mentor
- Shadow on-call rotations
- Review PRs together with focus on context

ONGOING:
- Weekly "system walkthrough" sessions
- Bug debugging sessions as learning opportunities
- Regular retrospectives on decisions and their outcomes

KNOWLEDGE CAPTURE:
- Mentor documents tacit knowledge as it's discovered
- Mentee asks "why" questions and records answers
- Create shared notes for future reference

Why It Matters

For Developers

Developing tacit knowledge makes you valuable to your team:

PROBLEM-SOLVING:
- Intuition for where bugs likely hide
- Pattern recognition from accumulated experience
- Mental models of system behavior

ARCHITECTURAL INSIGHT:
- Understanding why systems are designed this way
- Recognizing when "strange" decisions were correct
- Anticipating consequences of changes

THE HARSH REALITY:
Tacit knowledge makes you valuable but doesn't guarantee job security.
Google fired their Python team including a Python board member.
Technical irreplaceability doesn't protect you from organizational decisions.

For Teams

Managing tacit knowledge reduces risk:

REDUCED BUS FACTOR:
- No single-person knowledge dependencies
- Faster recovery from departures
- More resilient team structure

IMPROVED VELOCITY:
- Faster onboarding (weeks vs months)
- Quicker debugging with shared context
- More confident refactoring

BETTER DECISIONS:
- Historical context preserved
- Past mistakes inform future choices
- Architectural consistency maintained

For Organizations

Knowledge management protects institutional assets:

COST REDUCTION:
- Lower turnover costs
- Reduced production incidents
- Faster recovery from disruptions

SUSTAINABLE GROWTH:
- Scalable onboarding process
- Maintainable legacy systems
- Consistent architecture evolution

COMPETITIVE ADVANTAGE:
- Faster feature delivery
- Higher code quality
- Better system reliability

Common Mistakes

I’ve seen organizations make these mistakes repeatedly:

Mistake 1: “We’ll document it later”

SCENARIO:
Developer discovers system quirk.
Team: "Let's document that later."
Developer leaves 6 months later.
Quirk is forgotten.
Production incident occurs.

THE FIX:
Document tacit knowledge as it's discovered.
Later never comes.

Mistake 2: “The code is self-documenting”

WRONG ASSUMPTION:
Code shows what it does, so documentation is redundant.

REALITY:
Code shows what, not why.
Code doesn't show:
- Why this approach was chosen
- What approaches were rejected
- What could go wrong
- Historical context

THE FIX:
Comment the "why" and historical context.
Accept that code cannot capture decisions.

Mistake 3: “We have a wiki”

SCENARIO:
Team creates comprehensive wiki.
Initial documentation is thorough.
Wiki is never updated.
Documentation becomes outdated and misleading.
Developers stop trusting it.
Wiki becomes ghost town.

THE FIX:
Make documentation part of workflow.
Update docs in same PR as code changes.
Review documentation in code review.

Mistake 4: “We need senior developers”

ASSUMPTION:
Senior developers have tacit knowledge we need.
Hiring them solves our knowledge problem.

REALITY:
Senior developers have tacit knowledge.
If you don't manage it, you'll lose it when they leave.
Their knowledge wasn't managed at previous employer either.

THE FIX:
Create knowledge management culture.
Tacit knowledge must be actively transferred.
Hiring senior developers without management is borrowing time.

Mistake 5: “Tacit knowledge guarantees job security”

ASSUMPTION:
If I have irreplaceable knowledge, I'm safe.

REALITY:
Tacit knowledge makes you valuable to the company.
But companies make decisions based on many factors.
Organizational politics often outweigh technical value.
The paradox: knowledge that can't transfer is valuable to company
but doesn't protect the person who holds it.

THE FIX:
Develop tacit knowledge to become a better engineer.
Don't rely on it for career security.
Build professional networks and political awareness.

Summary

In this post, I explained what tacit knowledge is and why it matters for developers. The key point is that tacit knowledge is the undocumented understanding that makes experienced developers invaluable—the “we know more than we can tell” that accumulates through years of hands-on experience.

While tacit knowledge makes you valuable to your organization, the harsh reality is that it doesn’t guarantee job security. Companies make decisions based on many factors beyond technical value.

The solution is active knowledge management:

CAPTURE:
- Document the "why" through ADRs
- Record historical context in code comments
- Create runbooks with real troubleshooting examples

TRANSFER:
- Pair programming for direct observation
- Mentorship programs for structured learning
- Rotation to prevent knowledge silos

PRESERVE:
- Documentation as part of workflow
- Cross-training for redundancy
- Knowledge transfer sessions before changes

ACCEPT REALITY:
- Develop tacit knowledge to become a better engineer
- Don't rely on it for career security
- Build networks and awareness for true resilience

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion: Tacit knowledge makes developers hard to replace
👨‍💻 Michael Polanyi: Personal Knowledge (1958)
👨‍💻 Atlassian: Tacit Knowledge Management

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!