The Communication Tradeoff

Documentation-writing is not a goal in itself.

Code, tests, documentation – all of these are tools to communicate in writing with other programmers. That includes your future selves as it includes teammates and project collaborators.

Kent Beck, “The Documentation Tradeoff”:

In the end, write the docs you want to write. If no one reads them, or if readers find they are out of date, then consider not writing them next time. But don’t let anyone shame you into wasting time. The question is not, “Do you have documentation?” but rather, “Do you communicate clearly?”

Pick the tool you are able to wield. Not everyone is a master at prose. That’s not a problem if you can communicate in different ways.

Use the tools that fit existing communication structure. If you hang out with teammates all the time, an ephemeral conversation may actually do the job. If you’re part of an async team collaborating via git commits, you need something more permanent.

Express guarantees and assumptions in code if you can, where you can, so that this implicit information is made explicit in onboarding of new contributors.

Try different tools to gain insight into the thing you want to express. More often than not, writing a comment will clarify a problem so you can find a better, human-readable function name. Or even a different factoring, suggested by the flow of the prose. Same with tests. Comments are dead weight, commented code is the best.