Comment by Oliver Jones on "5 Things You Can Do To Write Better Code"

Nice stuff.

I have a suggestion: let's move away from the age-old myth that devs hate to write documentation. Like most myths it contains a kernel of truth, but that doesn't matter.

Instead, let's look at the things we DO generate, and figure out how to make them also explain our work to the user or the next dev.

Plans are documentation. Write 'em in the present tense. Write 'em as if for the next dev, not the product manager. "This module zumbinates non-recursive framisses, accepting immutable input and generating immutable output." etc.
Unit tests are, basically, documentation with examples. They happen to be runnable. A couple of extra comments, and there's usable docs.

I wonder what would happen if we start saying "Devs really love to help users and other devs. That's why we do this work. It's easy to explain what we do. It's called documentation."

Search Hashnode