| Home | Free Articles for Your Site | Submit an Article | Advertise | Link to Us | Search | Contact Us |
This site is an archive of old articles

vertical line

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 an 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.

So if time is short, please resist the urge to cut corners when it comes to software documentation. This may seem like a good way to save development time, but the results are bound to be disastrous.

Submitted by:

V. Berba Velasco

About the author:Dr. Velasco currently serves as a senior electrical and software engineer for Cellular Technology Limited (http://www.elispot-analyzers.de, http://www.elispot.cn, http://www.elispot.co.jp).


Arts and Crafts
Auto and Trucks
Business and Finance
Cancer Survival
Computers and Internet
Food and Drink
Gadgets and Gizmos
Home Improvement
Home Management
Kids and Teens
Legal B
Music and Movies
Online Business
Pets and Animals
Politics and Government
Recreation and Sports
Religion and Faith
Self Improvement
Site Promotion
Travel and Leisure
Travel Part B
Web Development

Copyright © 1995-2016 Photius Coutsoukis (All Rights Reserved).