[Mediawiki-l] Any leads on a basic wikisetup-and-configure instruction manual?

[Dave Sigafoos]

Bravo Jim .. I am standing and clapping <G>

DSig
David Tod Sigafoos | SANMAR Corporation



-----Original Message-----
From: mediawiki-l-bounces at lists.wikimedia.org
[mailto:mediawiki-l-bounces at 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