Bill Arnold <> wrote: > I think documentation is an imperative, for several reasons. But > first to mention that it's a management, not programmer, > responsibility that it be regarded as important, respected and kept > up to date. > > It's management's job to give developers the outline, table of > contents, to flesh out, so the programmer doesn't have to make these > decisions. > That's as it should be, because if each programmer is deciding the > outline, no two docs will match. Just for one example, I'm > management and I've prescribed that all documentation prepared in my > shop will have an appendix section that contains screen shots of > every form in the system. Anyone interested in looking into my > products knows this and exactly where to look for that particular > collection of information, and so on. > > The greatest benefits of documentation are that it gives the > programmer a road map of the entire system, something that cannot be > gleaned from looking at any program in the system. Also, the > documentation contains the original specifications and the thinking > behind why this was done instead of that. I put every single note, > even scans of notes on paper places, and emails, somewhere in the > doc. Yes, this produces large doc files, but who is counting? Nobody > reads the whole thing (save intros) end to end, but the doc is > searchable when a question comes up, and therein is great benefit. > Doc also contains lists of functions available to the programmer, for > easy search and perusal, to draw from and to prevent wheels from > being reinvented. > > I have seen terrible documentation, and even produced some that > didn't make the grade, but that doesn't mean doc is a bad idea, just > that we have to get better at it. Practice, practice, practice. And > better tools would help a lot. > > Lastly, I've seen so many times this effect: I'll write something > quickly, and put it where it belongs ... Then, some time later, > revisit what I wrote and say to myself "nah, that was completely > wrong" and then fix it. The thing is that the poorly written note > triggers the repair, so even it serves a purpose. > > In the last analysis, doc is a system, and like all systems, they > work if they are regarded as important, and fail if they are > neglected or considered unimportant. I've seen this in big companies > with systems management activities, such as problem management. One > company has it down to a science, another never got it.
I want to state that documentation is very important on the front end. Sorry but you need to have the roadmap for the developers to achieve. You can then have a test plan created to validate that what was asked for is accomplished. Sure having said doc updated as "changes" are done would be the perfect world. I'd like to see those said changes reflected in the actual code COMMENTS. I also tend to demand that a date is placed in those comments! Stephen Russell DBA / Operations Developer Memphis TN 38115 901.246-0159 http://spaces.msn.com/members/srussell/ -- No virus found in this outgoing message. Checked by AVG Free Edition. Version: 7.1.407 / Virus Database: 268.12.9/458 - Release Date: 9/27/2006 _______________________________________________ Post Messages to: [email protected] Subscription Maintenance: http://leafe.com/mailman/listinfo/profox OT-free version of this list: http://leafe.com/mailman/listinfo/profoxtech ** All postings, unless explicitly stated otherwise, are the opinions of the author, and do not constitute legal or medical advice. This statement is added to the messages for those lawyers who are too stupid to see the obvious.
