You love writing docs, don’t you?
You drop the link in chat - “hey, wrote this up.”
Your team gives you a 👍, maybe even a “nice one.”
But nobody actually uses it.
A week later, they ask you the same question.
6 months later, even you stop trusting what you wrote.
Here are 10 reasons why your documentation sucks.
1.
You open three docs for the same system.
Each one says something slightly different.
You don’t know which is right, so you ask someone.
Now there are four sources of truth.
2.
The most reliable signal in a doc isn’t the content.
It’s the last modified date.
If it hasn’t been touched in 6 months, odds are it’s lying to you.
3.
Everyone says “just write it down.”
Nobody says who’s supposed to clean it up.
So your wiki grows.
And trust shrinks.
4.
Most people won’t navigate your folder structure.
They search keywords.
And if nothing useful shows up in 30 seconds, they ask in Slack.
Your structure doesn’t matter if it’s invisible.
5.
Docs don’t age like wine.
They age like milk.
If there’s no owner, no expiry date, and no signal of freshness - assume rotten.
6.
You find a README.
It looks promising.
But the person who wrote it left the company last quarter.
You still read it - but you don’t rely on it.
7.
Even broken docs help sometimes.
They point you to someone who knows more.
That’s faster than digging through repos.
Wrong docs can still move things forward.
8.
Nobody wants to update a doc they didn’t write.
So people fork it.
Now there are two similar-but-not-same versions.
Both kind of wrong in different ways.
9.
People love structure - until they’re allowed to create folders.
Now there are 12 levels, and nobody knows where anything lives.
You end up searching by memory.
Good luck with that.
10.
Most documentation systems aren’t broken.
They’re just neglected.
It’s not a mess - it’s slow abandonment.
You don’t notice it… until you really need something.
You can’t fix what nobody owns. And most docs? Nobody owns them.
What can you do instead?
Top comments (0)