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 # 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 Symptom: First step: Run kubectl get pods -n billing First step: kubectl get pods -n billing If you see CrashLoopBackOff: If you see CrashLoopBackOff: Check logs: kubectl logs -n billing billing-service-[pod-id]Common cause: Database connection pool exhaustedQuick fix: Run this script: /scripts/restart-billing-safe.shDO NOT restart the master database node (causes 2-3 min downtime) Check logs: kubectl logs -n billing billing-service-[pod-id] kubectl logs -n billing billing-service-[pod-id] Common cause: Database connection pool exhausted Quick fix: Run this script: /scripts/restart-billing-safe.sh /scripts/restart-billing-safe.sh DO NOT restart the master database node (causes 2-3 min downtime) If problem persists after 10 minutes: Escalate to @platform-team in Slack If problem persists after 10 minutes: Related: See ADR 007 for why we use connection pooling Related: 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 // 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: Context: Why does this task exist? What problem does it solve?Prerequisites: What needs to be true before starting?Step-by-step instructions: Specific commands, not general guidanceCommon failure modes: What goes wrong and how to fix itWho to ask if stuck: Escalation path when documentation isn’t enough Context: Why does this task exist? What problem does it solve? Context: Prerequisites: What needs to be true before starting? Prerequisites: Step-by-step instructions: Specific commands, not general guidance Step-by-step instructions: Common failure modes: What goes wrong and how to fix it Common failure modes: Who to ask if stuck: Escalation path when documentation isn’t enough Who to ask if stuck: 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? What task on your current sprint would stall without you? And what would it take to document it so thoroughly that it wouldn’t?

The Best Code Is the Code That Survives You

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Technical Debt is a Financial Loan. Treat it Like One

The Art of (Architecture) Decision Making

How ADRs Help Engineering Teams Cut Costs and Reduce Technical Debt Over Time

Legacy Code Deserves More Respect Than We Give It

104 Stories To Learn About Go

105 Stories To Learn About Functional Programming

Technical Debt is a Financial Loan. Treat it Like One

The Art of (Architecture) Decision Making

How ADRs Help Engineering Teams Cut Costs and Reduce Technical Debt Over Time

Legacy Code Deserves More Respect Than We Give It

104 Stories To Learn About Go

105 Stories To Learn About Functional Programming

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps