Don’t Forget the Internal Software Documentation

Internal documentation. It’s one of the most frequent casualties in software development.

It’s not hard to see why. For most companies, time is money, and they frequently find themselves scrambling to release a product. It can therefore be tempting to save time by cutting corners—by shortening or eliminating development stages that appear to slow down the coding process.

Many programmers scoff at the importance of this documentation. “I know what I’m doing!” they say. “Time is short, and writing about my work will only slow things down. Besides, if something goes wrong, I know that I can fix it.” This is a terribly naïve and short-sighted approach. Such a cavalier attitude toward documentation can be disastrous to a company’s future.

It doesn’t help that programmers and engineers are notorious for having lackluster communication skills. It doesn’t help that documentation is a task that they seldom enjoy. The result is often an intractable mess—utter software design chaos.

A naïve programmer may think, for example, that in-code comments are unnecessary. I remember one engineer who laughed out loud when he saw me inserting comments into my code. “Look at this guy!” he chortled. “What a waste of time!” Admittedly, few programmers would carry this attitude to such an extreme; however, such perspectives are still implicit to a great many software developers.

It’s not just in-code comments that are important. In general, one should also document general software architectures, detailed designs, flows of logic, installation instructions, and so forth. The exact requirements will naturally vary depending on one’s specific situation, but as a rule, these are helpful benchmarks to strive for. The act of writing these documents can be tremendously helpful in guiding one’s design process, and it can provide helpful tools for design reviews and peer feedback. In addition, the developer’s goal should be to ensure that future programmers can figure out how it works without a great deal of hand-wringing or gnashing of teeth.

Unfortunately, many employees take the opposite viewpoint, and purposely scrimp on the documentation. Often, they do this to ensure job security for themselves—and sometimes, this tactic works. By scrimping on documentation, however, he may wind up jeopardizing the company’s long-term success. Besides, an astute employer knows that a programmer who documents well is worth far more than someone who holds his cards close to his vest. The latter may seem valuable in the short term, but ultimately, he’s a long-term liability.