Early in my career, I thought documentation was beneath senior engineers. Real engineers wrote code. Documentation was for technical writers or juniors with spare time.
I was wrong. Spectacularly wrong.
The best senior engineers I’ve worked with write prolifically. They document decisions, explain systems, and leave trails of knowledge. And that documentation is often their most impactful contribution.
The Expertise Problem
Senior engineers accumulate expertise. They understand why systems work the way they do. They know the history - the failed approaches, the constraints, the trade-offs that shaped the current design.
This expertise is valuable. But it’s locked in their heads.
When a senior engineer leaves, their expertise walks out the door. When they’re on vacation, decisions stall. When they context-switch, knowledge doesn’t transfer.
Documentation unlocks that expertise. It makes one person’s knowledge available to the entire team, forever.
Why Seniors Are Better at It
Documentation isn’t just writing things down. It’s understanding what matters, anticipating questions, and explaining context.
Juniors can document what they did. Seniors can document why. That’s a crucial difference.
Consider documenting a deployment process. A junior might write:
- Run
kubectl apply -f deployment.yaml- Check that pods are running
- Verify the service endpoint
A senior writes:
Before deploying, verify that the config change has been tested in staging. The payment service is sensitive to config drift - we had an incident in March 2024 where a missing environment variable caused silent failures.
Deploy during low-traffic hours (before 9am or after 6pm UTC). The rolling update temporarily reduces capacity by 25%, which can cause latency spikes during peak load.
After deploying, check the /health endpoint AND the payment-success-rate metric in Grafana. The health endpoint only checks basic connectivity - it won’t catch payment integration issues.
The second version prevents incidents. The first just describes steps.
Senior engineers know what can go wrong. They know the gotchas, the edge cases, the “obvious” things that aren’t obvious. That context makes documentation actually useful.
The Multiplication Effect
A senior engineer who hoards knowledge has linear impact. They can only help when they’re present, available, and asked the right question.
A senior engineer who documents has exponential impact. Their documentation helps people while they sleep, while they’re in meetings, while they’re solving other problems.
Consider the math. You spend four hours writing a document about your authentication system. Over the next year, twenty engineers read it. Each saves two hours of confusion, investigation, or bothering you with questions.
Four hours invested, forty hours saved. Ten-to-one return.
Now compound that. If you write one significant document per week, you’re generating hundreds of hours of saved time annually. That’s multiple engineer-months of productivity unlocked.
Documentation as Design
Writing documentation forces clarity.
Try documenting a system you designed. You’ll find gaps in your thinking. Edge cases you hadn’t considered. Assumptions you didn’t realise you were making.
I often write documentation before building. Not detailed specs - rough explanations of what I’m trying to achieve and why. The act of writing reveals problems with the design.
If you can’t explain it clearly, you don’t understand it well enough. Documentation is a forcing function for better thinking.
What Seniors Should Document
Not everything needs documentation. Focus on high-leverage areas:
Architectural decisions. Why did we choose this approach? What alternatives did we consider? What are the trade-offs? These decisions are expensive to reverse and easy to forget.
Operational knowledge. How do we deploy this? What do we check when it breaks? What are the failure modes? This knowledge is critical and often exists only in people’s heads.
Institutional history. Why does this weird code exist? What incident led to this defensive check? Context that explains the present state of the system.
Onboarding guides. How does a new engineer get productive? What do they need to know? This directly accelerates hiring impact.
Post-mortems. What went wrong? Why? What did we learn? This turns incidents into organisational learning.
Overcoming Resistance
Senior engineers resist documentation for predictable reasons.
“I don’t have time.” You have time for meetings, code reviews, and Slack. You have time for documentation. It’s a prioritisation choice, not a capacity constraint.
“It’ll get outdated.” Some documentation ages poorly. Write documentation that ages well: principles, decisions, context. These outlast implementation details.
“Nobody reads it.” Nobody reads bad documentation. Write documentation worth reading, and people will read it. Start with problems people actually have.
“I’d rather pair.” Pairing is great. It doesn’t scale. Documentation is pairing with the future.
Making It Sustainable
Documentation shouldn’t be a heroic effort. Build it into your workflow:
Document as you go. When you solve a problem, take ten minutes to write it up. The context is fresh. It’s much harder to write retrospectively.
Answer questions once. When someone asks you a question, answer in a document. Share the link. The next person with the same question finds the answer themselves.
Review docs like code. Include documentation in code reviews. If a PR introduces significant changes, where’s the doc update?
Have a home for docs. A wiki, a docs folder, something searchable. Don’t let documentation scatter across Slack threads and email.
Write for search. Use clear titles and keywords. Future readers will search for solutions, not browse. Make your docs findable.
The Career Angle
Writing documentation is good for your career.
It demonstrates leadership. Anyone can write code. Seniors who uplift the whole team are rarer and more valuable.
It builds visibility. Your documentation spreads your name and expertise across the organisation. People learn who knows things.
It creates artefacts. Code gets rewritten. Systems get retired. Well-written documentation persists. It’s a durable record of your contributions.
It develops writing skills. Clear technical writing is a superpower. Documentation is practice.
Start Now
If you’re a senior engineer who doesn’t write documentation, start this week.
Pick one thing: a system you own, a process you designed, a decision you made. Write it down. Not perfectly, just clearly.
Share it. Get feedback. Iterate.
Then do it again. And again.
The compound effect kicks in quickly. A few months from now, you’ll wonder why you ever thought documentation was beneath you.
Code is temporary. Good documentation scales.