A Selfish Appeal for DocumentationΒΆ

Writing code is the act of building a mental model of a problem, and then translating that model into executable software.

Writing documentation about software is the act of serializing this mental state. You can think about documentation as JSON for your mental state while programming. Documentation allows you to dump the information in your brain, in a format that allows others to reload into theirs.

Reading source code is the most inefficient way of transferring mental state. It also only conveys information on what the code does, not why it does it. My favorite rule around code comments fits well here:

Document the why, not the how

By writing documentation, you are able to load the why of your code into someone elses brain. Or reload it back into your brain 6 months after you wrote it. This allows you to complete your job faster, and also stops you from making the same mistakes over again.

Do yourself a favor and write documentation for your software.

Hey there! I'm Eric and I work on communities in the world of software documentation. Feel free to email me if you have comments on this post!