Bravo Jim .. I am standing and clapping <G>
DSig David Tod Sigafoos | SANMAR Corporation
-----Original Message----- From: mediawiki-l-bounces@lists.wikimedia.org [mailto:mediawiki-l-bounces@lists.wikimedia.org] On Behalf Of Sullivan, James (NIH/CIT) [C] Sent: Wednesday, April 11, 2007 8:45 To: MediaWiki announcements and site admin list Subject: Re: [Mediawiki-l] Any leads on a basic wikisetup-and-configure instruction manual?
Nice philosophy, but even in the real world (pro, big business coding on mega projects) documentation gets short shrift. Management sees code working, it doesn't see documentation working. Mike
I have seen great systems put together and wonderful functionality that management falls in love with, showers awards on its developer and recommends everyone use the new great tool. Then I see that one guy, only one guy, really knows the system. As the system gets used more and then becomes a critical piece of infrastructure, management gets worried, what of he leaves? They demand documentation, the programmer laughs. "Its self documented!". The guy eventually leaves but says he'll be available by phone if anyone needs help. Some poor soul is put in change of the system. Every day he wonders what to do if something breaks. He tries to understand the system but without docs there is little he can do. He tries reading the code, which is somewhat documented, but there is a lot of it and its not clear what calls what when. One day a system monitor goes off. "Malfunction in goobledegook". The poor soul has no idea what it is. Calls the developer who is happy to help. Things get fixed. Now the poor soul waits for the next failure, or worse, needs to update the OS the system is running on. Management begins loosing faith in the once great system and begins looking for a product with similar functionality from Microsoft. Management is now willing to be enslaved because they did not require their programmers to professionally document their work.
Documentation MUST be part of any system that is to be used by anyone other than the developer. It must be readable and complete. You expect your car to come with an owners manual, your garbage disposer, your washing machine and your iPod, none of which you ever plan to read. Why should code that others will use, especially when it is professionally developed, be any different? Short shrifting documentation is unprofessional and any good management should not stand for it.
Sorry for the rant... -Jim