An engineer left our team mid-project. He’d been there five years and was the only one who truly understood our transaction processing service. We knew he was knowledgeable. We didn’t realize how much undocumented knowledge he held until he was gone.

For a month, our deployment velocity dropped to zero. Every change required reverse-engineering his logic. A simple bug fix that should have taken two hours took two days because we had to understand the entire system first. We spent hundreds of engineering hours rebuilding context that should have been documented all along.

The service worked perfectly. The documentation was non-existent. Comments explained what the code did, not why it existed. The architectural decisions lived entirely in his head.

He wasn’t malicious. He was busy. He never made sharing knowledge a habit, and neither did we require it. When he gave his two weeks’ notice, we realized too late that we’d built a single point of failure into our team.

The Indispensable Trap

Some engineers believe that being the only person who understands a critical system creates job security. They’re half right.

You won’t get fired. But you also won’t get promoted. You can’t take a peaceful two-week vacation without your laptop. You can’t transition to exciting new projects because you’re permanently chained to maintaining the old one. You become a prisoner of your own expertise.

Deep technical knowledge is valuable. It’s often what gets you promoted to Staff or Principal levels. But the difference between a senior engineer and a senior leader is this: senior engineers make themselves valuable. Senior leaders make their teams capable.

The measure of your impact isn’t how much your team needs you today. It’s how well they function when you’re not there tomorrow.

You can’t transfer years of undocumented context during a two-week notice period. Knowledge transfer isn’t a final handover event. It’s a continuous architectural habit.

Here are three practices that make your work survive your departure:

1. Document the Ghosts

Junior developers write comments explaining what the code does. Senior developers write comments explaining why the code does it. Staff-level developers document the ghosts: the paths they explicitly decided not to take.

When the next engineer inherits your codebase, they’ll see a clunky workaround and think, “This is inefficient. I’ll just rewrite it.” Without context, they’ll step on the same landmine you successfully avoided.

Architecture Decision Records prevent this. Here’s a real example:

# ADR 003: Use 45-Second Timeout for Billing Service

## Context
Initial implementation used 30-second timeout. During load 
testing with realistic African mobile network conditions, 
we observed legitimate transactions completing in 31-35 
seconds due to payment provider API latency.

## Decision
Increased timeout to 45 seconds.

## Consequences
- Slower user experience (acceptable tradeoff)
- Must monitor p95 latency; if it exceeds 40s consistently, 
  we need to optimize the service, not reduce the timeout
- If payment provider improves API performance, we can 
  revisit this decision

## Alternatives Considered
- Keep 30s timeout, retry failed transactions: Created 
  duplicate transaction risk
- Async processing: Adds complexity, doesn't improve user 
  experience for time-sensitive payments

This ADR saves the next engineer from making the same mistake twice. It shows what you tried, what failed, and why the current approach exists.

2. The 3 AM Runbook

Most documentation gets written at 2 PM by a calm engineer with coffee. That documentation is useless during actual incidents.

Real runbooks need to work for a panicked engineer at 3 AM who’s never touched this system while the production database is degrading.

Bad runbook:

“Ensure the cluster state is healthy before proceeding.”

Good runbook:

Symptom: Billing service pods in CrashLoopBackOff
First step: Run kubectl get pods -n billing
If you see CrashLoopBackOff:
  1. Check logs: kubectl logs -n billing billing-service-[pod-id]
  2. Common cause: Database connection pool exhausted
  3. Quick fix: Run this script: /scripts/restart-billing-safe.sh
  4. DO NOT restart the master database node (causes 2-3 min downtime)
If problem persists after 10 minutes: Escalate to @platform-team in Slack
Related: See ADR 007 for why we use connection pooling

The difference is specificity. The first version requires expertise. The second version provides a checklist that works even when your brain doesn’t.

3. Context Over Cleverness

Highly abstracted, clever code that only you can read isn’t a feature. It’s a liability.

I’ve seen brilliant engineers write elegant, sophisticated solutions that get completely rewritten six months after they leave because nobody else could maintain them. The cleverness that made them proud made the code fragile.

Boring, readable code survives. Undocumented clever code gets rewritten.

This doesn’t mean write bad code. It means optimize for the next person who has to understand it, not for demonstrating your mastery of advanced language features.

If your code requires deep expertise to modify, add comments that build that expertise:

// Using binary search here because linear search was too slow
// for datasets >10k records (measured at 3.2s vs 45ms)
// If dataset size drops below 1k, linear might be simpler

In 2026, documentation increasingly serves as context for AI-assisted development. If your team uses LLMs for codebase onboarding, your ADRs and detailed comments become training data that helps new engineers ramp up faster. But even without AI tools, clear documentation helps humans understand your work.

The Two-Week Notice Test

Here’s an exercise to test your own replaceability:

Look at your team’s current sprint. Pick the one task that would completely stall if you were unavailable tomorrow.

Don’t fix it by writing code. Fix it by writing documentation.

Spend one hour creating a runbook:

Then test it. Hand the runbook to a teammate and ask: “Could you complete this task using just this document?”

Their answer tells you if your documentation is good enough.

If they need to ask you clarifying questions, your documentation has gaps. Fill them. Repeat until they can execute without you.

The Real Career Advancement

Some engineers worry that making themselves replaceable makes them less valuable. The opposite is true.

Teams that depend on knowledge-hoarders can’t scale. Teams that depend on knowledge-sharers can.

When you document your expertise, you free yourself to work on harder problems. When you make your current role easy for others, you create space to grow into the next one.

The engineers who get promoted aren’t the ones who hold knowledge. They’re the ones who multiply their impact by sharing it.

Make yourself replaceable. It’s the fastest path up.

What task on your current sprint would stall without you? And what would it take to document it so thoroughly that it wouldn’t?