Let’s be honest. Who likes writing documentation? Nobody. It’s the kid who always gets picked last. You pick him because he’s there, not because you want to play with him.
Documentation came straight out of the ninth circle of hell. Dante had no idea what was coming. He thought treachery was rock bottom. He never had to write a Confluence page.
And of course it’s every boss’s favorite ritual. Did you document this? Did you document that? The rest of the religion is optional.
Then one day you get older.
You start forgetting things.
Not big things — small ones. Why you wrote that weird if. What that service even does. Whether the thing you’re about to “just quickly fix” was a bug or the only reason the process works. So you start writing it down. Not because a boss asked. Because you can’t trust yourself anymore.
The person you’re really writing for isn’t your boss anymore. It’s you, six months from now — tired, staring at your own code like a stranger wrote it. And the stranger left no notes.
And right about then, you notice everyone missed the point.
Documentation for its own sake isn’t the point. Neither is design for its own sake, nor a comment that exists only to make the code look more professional. The point — the only point — is to make delivery smoother, safer, and less dependent on one tired human memory. Everything else is decoration.
What to write
A document has exactly one job: make the next person faster, even if the next person is just you. Anything else is performing ritual for the sake of the ritual. Let’s see what I’m talking about:
1. The design doc. The shape of the thing before a line exists, and why this shape: standard vs custom, boring option vs trendy miracle. Skip it and you build the wrong thing beautifully, then tear it out next quarter.
2. The README. Three sentences: what it does, why it exists, who to blame. What you wrote instead: nothing. Or # project. Now the new hire has to come find you in person — the one outcome you were trying to prevent.
3. The why-comment. Not // loop through the users sitting on top of a function that loops through the users. Thank you, very insightful. The why-comment is a flashlight you leave in the dark: // batch in 200s — the API 500s at row 201. Skip it and someone reverts your fix, resurrects the bug you killed, and ships it on a Friday.
4. The runbook. Not forty wiki pages. Just lines that matter.
Deploy: run this.
If it breaks: roll back with that.
If that fails: call this person and apologize.
Written calm on a Tuesday, read by someone whose hands are shaking at 2 a.m. Without it, the loudest voice in the incident channel becomes the rollback plan.
5. The handover. The scheduled job nobody knows about. The shared account whose password lives in exactly one human skull. Written before vacation, read the moment you’re on a beach and unreachable — which is also, by Murphy’s Law, the moment it breaks.
Then you write it
Here the trap springs: there is no silver bullet. A library, a CLI, and a payments service want three different kinds of docs. There’s talk that a universal best-practice template exists. There’s also talk about the Yeti. Everyone claims he exists. Nobody has ever seen him.
So stop hunting for it. Two questions, that’s all: who reads this, and what will they do with the knowledge they get from it? Write for them. And for yourself.
And leave it where we’ll walk into it. We are lazy. If it doesn’t hit us in the head, we won’t go looking for it. README in the repo, the why in the comment, the design in the pull request. Nobody opens the wiki. Everybody opens the file they’re already in.
The uninvited but more-than-welcome partner arrived a few years ago. The same partner that reads your scary code and helps you drain the swamp will hand you a confident, fluent, sometimes-hallucinated first draft of the README you would never write. It invents the odd thing, so you read it and cut the two lines that are lies — still infinitely more than the zero drafts you were ever going to write.
But don’t forget: you own the truth. It just does the typing.
And to your boss, the second it’s written, it’s done: a documented task feels managed, a managed task feels delivered, somebody wrote something, case closed. Nobody checks whether the page is any good.
Writing it is admin. Knowing it works is engineering.
This is the floor Dante hid really, really well. Just when you think you’re in the clear, here it comes. How do I even know if all this effort helps?
Because even when the docs exist, their impact is gloriously unmeasurable. The question was never “did you write it?” — it’s “what did we get out of it?” Did it make the next person faster? Is our software better quality? Are users happier? And, cherry on top, none of it fits in a ticket.
The only way to measure it is to watch the shadow it casts on everything else:
The onboarding clock. Days from a new hire’s first morning to their first real commit. Good docs turn “two weeks of asking where staging is” into three days.
The “quick question” counter. Every “hey, quick question, how do I…” in your DMs is a document that doesn’t exist, or exists and is hard to find. Watch the number drop.
The rework tax. How often you shipped something and tore it out a quarter later because the shape was wrong — not a bug, the whole idea. That’s quality, measured before users do it loudly and for free.
The incident replay. After the next outage: did anyone open the runbook, and did it help? If it sat there unread while three people guessed, it’s a bedtime story with nice formatting.
The vacation test. Phone in a drawer, one week. If it rings on day two because only you can deploy, your bus factor is one and your documentation is a rumor.
None of these are story points. All of them are real outcomes.
A good document makes someone faster. A bad one makes everyone feel responsible while changing absolutely nothing.
That’s the difference between engineering and decorating the wiki.
So, schmocumentation
Nobody likes it. But the kid who got picked last grows up to be the only one who remembers the good plays — and how good a player you were. You forgot. How sharp you were that quarter. How good those days felt. The page remembered all of it, quietly, while you moved on.
That’s what documentation really is. Not a chore your boss invented to feel in control — a note for the tired, forgetful stranger keeping this software alive after you. And nine times out of ten, that stranger is just you: six months older, trying to remember how you ever pulled this off.
By order of thebeanengineer.com — document it, schmocument it, just make the next person faster.
Be an engineer. 🚀