Documenting our code

Everybody likes helpful, clear documentation, but not when it is out of date and unrelated to the current code base.

There is a general principle in software that the more separation there is between two related ideas, the more pain they will bring. As an example, think of some code that reads some obscure file format that nobody remembers. All works well, so long as you are reading files in that old format. Then you upgrade the application, that old file format is no longer supported, and everything breaks. The code was separated from the data content in those old files. The files didn’t change but the code did. We didn’t even realize what was going on.

It’s the same with documentation. The worst documentation is often contained in the glossiest productions. These are artifacts written a long time after the code was created by teams with separate skillsets – copywriting, graphic design, and so on. Documentation updates are the...