There’s a moment most developers don’t notice when it happens.
You’re writing something.
Maybe a README.
Maybe a quick guide.
Maybe just a comment to “explain things later.”
And without thinking, you write it like this:
“Just run this…”
“Obviously, you need to…”
“Make sure you already have this set up…”
It feels normal.
Because in your head, it is obvious.
Until Someone Else Reads It
A new developer joins.
Or a teammate picks up your work.
Or worse, you come back to it weeks later.
And suddenly…
Nothing is obvious anymore.
That “simple step” is confusing.
That “quick setup” is missing pieces.
That “just do this” assumes too much.
And now, instead of helping…
Your documentation slows things down.
The Shift Most People Miss
Documentation stops being about you the moment you write it.
But most of us don’t adjust.
We write from memory.
From familiarity.
From inside the system.
Not from the perspective of someone seeing it for the first time.
What Makes Documentation Actually Work
It’s not more detail.
It’s better awareness.
Good documentation quietly answers questions like:
“What am I supposed to do first?”
“What might go wrong here?”
“What am I missing that everyone else seems to know?”
Because that’s where people get stuck.
Not in complexity.
In assumptions.
The Problem With “Just Enough” Docs
A lot of teams aim for “just enough documentation.”
But “just enough” for the writer is often not enough for the reader.
So users:
• Fill in gaps incorrectly
• Make assumptions that break things later
• Lose confidence before they even start
And once that confidence is gone…
It’s hard to get it back.
A Small Habit That Changes Everything
Before you write anything, pause and ask:
“What would confuse someone seeing this for the first time?”
Then write for that version of the reader.
Not for yourself.
The Real Job of Documentation
It’s not to prove you understand the system.
It’s to make sure someone else doesn’t feel lost using it.
Final Thought
Good documentation doesn’t sound smart.
It makes the reader feel smart.
If you’re building something and people keep getting stuck, asking questions, or misusing your product…
It’s rarely because they’re not capable.
It’s because something wasn’t made clear.
That’s the gap I focus on fixing.
