Let’s get this out of the way: no one gets into software because they love writing documentation.
But that doesn’t mean it’s not essential.
Way back in 1975, Fred Brooks wrote The Mythical Man-Month, a book so enduring that engineers still pass it around like it was published last week. One chapter, “The Documentary Hypothesis”, nailed why writing things down matters in software projects.
And it still holds up.
Why Write Docs At All?#
Brooks gives three reasons. They’re painfully obvious and yet still ignored:
- Writing exposes the gaps. It’s easy to say, “Yeah, we’ve decided how this feature works.” But try putting it in words, and suddenly: wait… how does it handle edge cases? Oh, right. We didn’t think that through.
- Communication breaks down fast. You assume everyone on the team knows what you know. They don’t. A written document saves you from playing Slack tag with five engineers and re-explaining the same thing in five different meetings.
- Docs become your dashboard. A good spec or plan lets you check in, see if you’re off track, and course-correct. It’s not a “management total-information system.” It’s just a shared brain outside your own.
That was the 70s. Then came the 90s.
Waterfall and the Overcorrection#
In the waterfall era, documentation became religion. Specs were 80 pages long. Gantt charts filled the walls. Teams would spend months documenting a plan they’d spend years building, only to find the final product didn’t match what users needed.
We swung too far. So Agile came swinging back.
Agile Was Right… Mostly#
The Agile Manifesto reminded us of value:
Working software over comprehensive documentation.
Not instead of. But many teams heard “docs are overhead” and ran with it.
So we ended up with a generation of codebases that work, but no one understands them. Onboarding is painful. Context gets lost. Decisions vanish. The same questions get asked over and over again.
Sound familiar?
Where We Are Now#
Today, we're somewhere between cargo cult waterfall and chaotic agility. And it’s clear: docs are still essential, just in the right amount, and for the right reasons.
Write down:
- What you’re building and why
- How it’s supposed to work
- Who’s responsible for what
- What decisions got made (and when)
- What tradeoffs were accepted
That’s not “comprehensive documentation.” It’s just enough not to get lost in your own project.
Good Docs Make Good Teams#
At Dosu, we’ve seen it repeatedly: the teams that document their thinking, even a little, move faster, onboard smoother, and make fewer mistakes. It’s not about perfection. It’s about clarity.
But no one wants to sit down and write documentation, right? Dosu Does!
As your team works, Dosu automatically captures decisions, tags discussions, and builds a living document. So you get the benefits of documentation without the overhead.
Fred Brooks would’ve loved it.