Documenting versus fixing

When you would rather have something properly documented than fixed.

In engineering, documentation is crucial although we don’t like to think about it. Documenting the processes, implementations, architecture, problems that we encountered and the ways we solved them helps a lot in the future. Not only to the people that will have to work on the things you worked on, but also to yourself since you will most likely forget what you worked on 6 months ago. Having the ability to look up the reason why something was done the way it was done is priceless.

I listened to the Ruby Rogues podcast after a long while, and the main reason is that my friend Vlado was a guest on it with his cool and useful gem called activerecord-cte. One of the hosts said something like this:

If you want an engineering team to fix any sort of outstanding issue, give them a choice to either fix the issue at hand or document it so it can be fixed later. Engineering will fix it in no time given that option.

This quote rings so true to me, since the detachment between wanting to document something and digging in to fix it is huge. The best “documenters” I met were people that originated from support, and I understood their willingness to document stuff as much as possible.

If you tried working in support for just a week, you would understand why they value good documentation above all other things. It is so much easier to link an article or a how-to document when a hundredth customer asks you the same question over and over again. It saves a lot of time for these agents and removes a lot of confusion because you might recite something different every other time someone asks you (or even forget stuff).

We have this great anecdote in engineering where we explain the problem to a coworker, or if we lack coworkers, we can explain it to a rubber duck. Just the process of explaining the issue increases our own understanding of the issue, and usually brings out a solution while we are explaining it. Whiteboards can help in solving problems by drawing them out and giving a bigger perspective. This has worked wonders for me personally whenever I faced a hard-to-solve issue that sat there unsolved for what seemed like ages. Though we do not need to document every bug that happens, as I already mentioned, incident post-mortems are a great way to understand what happened and how we can learn from it to prevent it from happening in the future. Learning by teaching is the best way to learn in my opinion because the more you teach, more you learn.

If you want your code to last, you have to make sure people want to work on it and it’s hard to work on something you don’t understand. Documentation, specifications, and inline docs all add to the readability and understandability of the code at hand. If you lack one of them it’s okay, but if you lack all of them, it will be very hard to persuade people to work on your project.

Thanks to Tom White for reviewing and helping me improve this post.