.. post:: Sept 24, 2016
   :tags: docs, why not how, tips

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.