Documentation is JSON for the Brain

When you are writing software, you build a mental model of the program in your brain. This is how you make decisions and reason about how the program might work, how data flows, or what designs make the most sense.

A large amount of the time spent “programming” is actually building a mental model in your brain. You spend time understanding how and why things are put together. Programmers often talk about how interruptions can stop them from being productive for 15-30 minutes afterwards. This is because they are losing the mental model that they have spent time building.

Reading documentation is the quickest way to load mental state into your brain. It gives you a shortcut, faster than reading code, to understand what the code is doing, and why. Writing documentation is the best way to preserve the mental model in your mind, and turn it into written words for later.

Documentation is JSON for your mental state. You should write docs so that whoever is maintaining your code will be able to get up to speed quickly, and understand why certain decisions were made. That person might even be you in 6 months.



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!