Thu, 09 Aug 2007

Documentation . . . Ya gotta love it . . .

I write software and maintain systems. I'm in the middle of creating some documentation for a system I wrote and have maintained for several years. The framework for this documentation was created by someone and is expected to be used to run the system -- a "run book".

Let me say that, like most programmers, writing documentation is not my most favorite thing. I realize that documentation is necessary. It's just that writing it can be a pain . . . especially if you are using someone else's outline or framework. I'm trying to fill in elements that I don't understand and it appears to me that there is excessive documentation including repetition which can cause maintenance problems. The way I look at it is that each piece of information should appear only one time, if possible, to ease update. There is nothing worse than documentation which is out of date. It is almost worse than no documetation at all since it can send you down the wrong trail when problems occur.

Repetition is also a problem. In the framework I am using, backups are referenced in at least three places. This makes it likely, that, should the process change, at least one of these places will be missed.

OK, I have expressed some frustration . . . Now back to it . . .

posted 13:05 [/Technology] permanent link