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. Bill > Most documentation is a waste of time and money. It is > expensive to produce. It is frequently not maintained, > rendering it useless. And it makes two very "iffy" > assumptions: one that the author knows how to write and two > that the reader has a basis for comprehension. > > Heresy? Perhaps. > > My response to documentation (or lack of it) is that if I am > going to fix your code or expand it or whatever, I had better > be smart enough to understand what is there. If I cannot do > that from looking at the source code and perhaps a few test > cases, then I should not be messing with the stuff. Would > you want to be under the care of a medical doctor who had to > rely on his class notes? > > Agile programming? It's an oxymoron. If one ordinary woman > can give birth to a child in nine months, nine agile women > should be able to do it in one month. > > HALinNY > _______________________________________________ Post Messages to: ProFox@leafe.com 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.
