My likely unpopular opinion on software documentation

Here's an expression that summarizes my opinion on software documentation.

accurate >= none > wrong

• Accurate documentation saves work.
• No documentation indicates that you'll need to put the work in to understand.
• Wrong documentation misleads.

Hopefully that's not too controversial.

Here's my beef. Accurate documentation can very quickly become wrong, and no documentation is oftentimes as good as accurate documentation, especially if the code being documented is well-written. And in order to reconcile wrong documentation you need to read it and the code, which likely takes longer because the documentation makes you think the code works in a different way than it actually does.

So it's probably better to just spend more time writing better code that may never need to be documented.

All that said, I'm not against documentation. But as with all writing, it's important to know who you're writing for. Time spent documenting that convoluted private function that only the five other developers on your team will look at is probably better spent de-convoluting that private function. Time spent documenting your system's architecture or a public API is absolutely worth it. Just make sure you're willing to devote time to keeping it accurate.