Why write technical documentation?

The best documentation is no documentation: code should be self-explanatory.

All the lazy developers in history

Writing documentation is hard.

We try to find excuses and rationalize and lie to ourselves so we can feel better about with the fact that we should be doing it, but it’s “too much work”.

Here are two good reasons to try and convince you to start writing documentation, and help you while you help others, too:

1. You won’t remember that 6 months from now

Just fixed a bug? Written a new feature? Cool! You may think you know your code now, but if you come back to it 6 months later, you will have forgotten most about. It will be as if someone else had written it.

Write it down now that it’s fresh on your mind. You will be happy you did it when you come back later looking for help finding out how “this” was done and how does “that” work.

Which bring us to…

2. Grep is sub-optimal

Why browse the sources and reverse-engineer code when you can read a paragraph that’s written for humans? It’s not efficient to read 600 lines of code and run them in your head when you could simply google it.

Remember, code is for computers and documentation is for humans. If you are reading this, that means you’re probably a human. Optimize for your time, too.