Dragging Documentation Out of the Dark Ages
Confessions of a corporate dung beetle rolling docs uphill.
Yet again I find myself the dung beetle of change in a large organization
This time, the hill I’ve chosen to climb is docs-as-code and documentation quality.
I’m untethered from the team, sitting on the outside, scanning the industry, trying to apply what I learn. I am well aware that this is not how it should be.
The project is in Python. It’s a shared AI capability. I know neither of these things.
On one hand, I think: just tidy up, publish, and move on.
On the other hand, I can’t help drifting toward information architecture and content design. Big-picture thinking is my default setting.
And here’s the big picture: documentation is still treated like a checkbox.
You will have read that statement 50 million times in your tech career and yet here we are.
Leaders know platforms depend on it, but in practice, documentation is treated as a knowledge dumping ground. Write it down somewhere and the job is done. That’s not documentation - that’s archaeology waiting to happen.
Real documentation is an architecture. It’s flows that guide you (hello, Diátaxis), reusable assets that keep teams from re-inventing the wheel. And reuse isn’t nice-to-have — it’s how we cut variance and deliver faster.
So here’s the ask: if we want reuse, we have to get serious about documentation. Not as lip service. As accountability. It’s time to treat documentation like delivery— tie it to OKRs, give it weight, and finally drag ourselves out of the dark ages
Because until documentation is measured like delivery, teams won’t have the time, leaders won’t see the results, and we’ll stay in the dark ages while others are already writing docs for humans and machines.