Sunday, December 24, 2006

The Absolute Need to Document

During my time in the field of QA and testing, I have learned to appreciate the need for documentation. As a student, it always seemed that commenting and documenting your code was a frivolous waste of time and energy. To be truthful, as a student, documentation was a waste of time and energy. Nobody will see your code ever again after it's turned in. Nobody will be inheriting your code later on, and have to struggle to figure out what the hell you were doing with your code. Also, most of my projects simply weren't large enough to warrant thorough documentation.

However, this lack of documenting creates bad habits that are passed on after one eventually graduates and enters the work force. The size and complexity of the programs one works on become much grander in scale, and yet the skill and desire for proper documentation is not present. This creates more problems than you can know, and has caused severe headaches and a lot of wasted time in my case.

If an alpha-geek super programmer makes you an amazing program that does exactly what you want, is completely localized, and has very few defects, I'm happy for you. If he or she didn't document it, you're completely screwed. When the program in question needs to be updated, added to, patched, or modified in any way (which is almost a certainty), you are dependent on the original programmer to be able to remember how they implemented the program the first time (assuming that the original programmer still works for you), or you must have another programmer waste considerable amounts of time understanding how the program works. If, however, that original programmer effectively documented the program in a way that made knowledge transfer possible, you can have another programmer pick up the slack with much less ramp-up time.

In this world where knowledge is king, there must be a way to transfer knowledge effectively, or it is essentially lost. Enforcing documentation is simply a smart way to protect your company assets. You cannot assume that the developers who know how something works will work for you eternally, and you must provide a way to communicate the internal workings of the program to others. Otherwise those that need to know how something works (QA, managers, other programmers) will waste the programmers time over and over again while they explain how their program works.

In addition, I've found that documenting helps me to focus on what I'm working on, and flesh out implementation details that I'd put off in the back of my mind. By having it down on paper, it's like I have a map of exactly what I need to create and implement. Documenting is about looking ahead, thinking ahead, and spending time now to save it in the future. So the next time a programmer tells you he doesn't need to document his program, tell him to suck it up and do it anyway, because documenting isn't about him or her - it's about everyone else. Spending a couple hours now to document a program will save you and others hours and hours later on.


Anonymous said...

majority viewing postings doxium dynamics abdn dividing melodies opec neutrality usefulness
lolikneri havaqatsu

Anonymous said...

Great post, I am almost 100% in agreement with you

Anonymous said...

top [url=]online casino[/url] brake the latest [url=]free casino bonus[/url] free no deposit hand-out at the leading [url=]casino online