[GRLUG] Newbie Distos [Was: Re: Upgrading Firefox]

[Adam Tauno Williams]

> Speaking of "good documentation," what's
> that any more?  Man pages are pretty minimal,
> where they exist at all any more, and mostly suggest
> you read something somewhere else.  Man pages
> go back to the earliest Unix, and why they have
> been more or less abandoned in recent years is
> unclear.  In the past they were the documentation.

They accept patches I'm sure. :)

> And "HowTo" pages.  I don't see them referred to
> much in this group.  Is that still a current concept?

No.  Go searching for HOWTOs, most are beyond antique.  They've been
replaced by either Wiki-ish things or actual books.  O'Rielly prints
many...  That and a great many things just work.  Hooking up a dial-up
connection, VPN connection, or wireless connection - provided your
hardware works - is now just a pointy clicky thing on any mainstream
distro.

> i.e., do people write them any more, or keep them
> current, or is most information now at project 
> sites and spread over endless blogs and Q&A websites?

Yea, it is pretty bad.  It goes down to one of my own favorite quotes:

"Writing good documentation is hard. It's much harder than writing
code." 
Chris McDonough, ZopeMag Interview July 2003

Hence the terrible state of documentation for both Open Source projects
and proprietary projects.   I've written a fair amount of documentation
<http://docs.opengroupware.org/Members/whitemice/wmogag/file_view> and
the documentation takes several times longer to write than the code to
just-do-it.  You numerously run into
oh-crap-that-doesn't-make-any-sense-unless-I-explain-X-as-well-and-probably-Y-a-bit-better,  Writing documentation often gives one the sensation of falling into a black hole.

> A guess is that that how-to information is better 
> for more stable projects.  But one often enough 
> reads that the authors don't have time to write
> documentation.

Yep, limited resources.

-- 
OpenGroupware developer: awilliam at whitemice.org
<http://whitemiceconsulting.blogspot.com/>
OpenGroupare & Cyrus IMAPd documenation @
<http://docs.opengroupware.org/Members/whitemice/wmogag/file_view>