3. Documentation is Code

Date: 2024-04-10

Treat documentation the way you treat code

From the cover of The Best Software Writing I:

Yeah, I know: programmers hate writing. And when, for some reason, they are somehow forced to write down something, it reads like the repair manual for a DC-3, or the result of consolidating all the "don't do this" examples from an English style guide into one page. Well, enough is enough, I say. At my own company, we instituted a policy: we only want to hire software developers who can write, and write well. Just try submitting a resume with grammatical errors or a cover letter that reads like it was written by that guy who translates those instruction manuals for really cheap consumer electronics, I dare you.

If you’re writing software, good documentation is a necessity, especially if other people will see or contribute to the codebase—or if you yourself plan on coming back later.

If you’re only using the software, you almost always could benefit from documentation that is missing, whether it be instructions on how to use it—or an explanation of when you should and shouldn’t use it.

If you’re contributing to a codebase, the speed at which you can start effectively contributing is correlated to how good the documentation is, as long as the code itself isn’t convoluted.

Whether you’re an author, contributor, or just an end user of the codebase, the quality of the documentation affects your experience, directly or indirectly—so writing good documentation matters.