No one reads the documentation — and that shouldn’t stop you


I could make a post with the perfect tone mix of “amusingly angry” and “cynical tech guy” on how no one ever reads the manual, but this is not about making a point on how clever “we” are versus how dumb are “they”. I can recognize that once or twice I’ve been tempted to answer a basic query on software with a RTFM or JFGI (which, if you don’t know the acronyms, are not in the slightest the polite and correct way to address a question), but falling for raging retorts is what slowly turns any workplace into a toxic one. Instead, I’m going to be constructive, and point out how to avoid a critical pitfall for software development.

People that have worked with me know how much of a dedicated documentation writer I am. Well, I actually enjoy writing as an activity (this blog bears witness to that fact), but reference creation is not the most enjoyable activity. So no, I don’t write technical papers as a hobby; I do it because it is a necessity.

Time and time again, you’ll find yourself going back to old projects. Maybe to add a new feature, or perhaps to reuse a library that can be helpful on new designs. Or perhaps it’s a legacy component that requires an upgrade, that you have inherited from an employee that no longer works in this company. I guess I don’t need to tell you how fast paradigms and frameworks evolve, change and are discarded. So chances are high that the old project is outdated. That means that any kind of modification, unless correctly explained, will be a painful experience.

Let’s take a minute to consider this: What do I mean with documentation? Well… More than on the functional level, I am referring to the technical records that explain design decisions, inner workings and intricacies of the code. When you are developing a specific feature, the reasons behind the implementation you adopt can be obvious — and notice the italics there. Your train of thought is fresh, and the many deductions extracted from the requirements analysis brought you towards specific decisions. But as time passes, the basic reasoning behind those choices will fall, and you will stare puzzled at that fragment of code.

Now, imagine the scenario where that code isn’t even yours. You better enjoy solving riddles, because you just got yourself one.

Sometimes, you don’t really need to invest long hours into drafting, polishing and editing your writing. A few lines can do, and diagrams or graphics are sometimes even more helpful, as the proverb goes.

As a final footnote, make sure that your record gets proofread by a peer. Otherwise, you might fall into the trap of allowing a concept that you believe obvious to fall into oblivion.

Answering the underlying question: why should you write documentation? Because memory fades, and you need some sort of insurance protection against future extensions.

Originally published at Álvaro G. Cachón.