[ale] TFM - was: I am so tired of Linux Fanatics

Thu Jul 8 11:04:08 EDT 2010

Jim,
This is a place where an ounce of initiative would be worth a ton of
complaining.  Where could a person get themselves hooked up with whoever
maintains (or doesn't maintain) man pages?
I started working on developing a rewrite of some man pages for a few
packages I use a lot, so the examples were at the top and not obscure.
Many newbies believe foobar is a real linux command (I know from testing
a couple hundred new linux users).  Nobody has time to take on the man
pages for 30000 packages, but if every one of us took on 1 or 2 of the
man pages then the "F" in RTFM might be "fine", "fun" or "fabulous."
What say you?

-Wolf

-----Original Message-----
From: Jim Kinney <jim.kinney at gmail.com>
Reply-to: Atlanta Linux Enthusiasts - Yes! We run Linux! <ale at ale.org>
To: Atlanta Linux Enthusiasts - Yes! We run Linux! <ale at ale.org>
Subject: Re: [ale] I am so tired of Linux Fanatics
Date: Thu, 8 Jul 2010 09:36:43 -0400

My greatest "AH HA!" moment reading man pages was when I discovered I
could search for terms within man pages by hitting /<search term>
or /"search term" when it had spaces.

And yes, release notes should be merged into the man pages as a "current
version" section. I recently spent many days trying in vain to get a
particular aplications client libraries to compile. Total fail. Turns
out there was a blurb in a .2 version release notes that briefly pointed
out the client libs were merged into the server libs and not needed as a
stand-alone anymore. Since entire application had various version
numbers for the different pieces, I had grabbed the latest of each. 

at least there _were_ release notes!

eons ago (before SuSE drank the kool-aide and open-sourced their
installer) I was tinkering with a SuSE installation issue. They had no
release notes on their installer. They had notes on the distro but their
installer was a black box. And it was failing to run on my chipset (that
was about 2 years old so it should have been supported). End result is
RedHat installed nicely and their notes on their installer covered the
chipset initialization failure and provided a workaround (don't ask. It
was like RedHat 4.2 era). Thusly, I wound up firmly in the RedHat camp
since their output was more professional and robust and informative and
open. And unlike the Debian installs at the time (which always worked -
BTW) did not require that I know memory address space values (in hex of
course) in order to accept a configuration during installtion. Granted,
if I just hit "OK" on everything it all worked but it felt like a dead
vertical learning curve while carrying a load of lead bricks by a cord
in my teeth while climbing a greased rope that was on fire.

And from that was born Ubuntu....  :D

On Thu, Jul 8, 2010 at 7:34 AM, Paul Cartwright <ale at pcartwright.com>
wrote: 

        On Wed July 7 2010, Jim Philips wrote:
        > The problem with RTFM is the assumption that the fine manual
        was well
        > written in the first place. I have been using Linux since 1995
        and I have
        >  always felt that the man pages were written in exceptionally
        poor fashion.
        > The immediate underlying assumption is that you need to know
        about
        > *everything* and that most basic functions of a command are
        beside the
        > point. The man page for grep is an excellent example. They
        never go
        > straight to the point. The high use examples are always buried
        somewhere
        > that you would least be likely to look for them. The "F" in
        RTFM is not at
        > all deserved. How can I find a file containing "x" in my home
        directory?
        > The question will only be answered in the most convoluted way.

        I forget the man page I was looking for once, but the option I
        was looking for
        was somewhere in 3,000 lines of gobbledegook, and I couldn't
        find it.. some
        of those man pages are just totally outrageous! This App I used
        to install
        came out with a new version, and it didn't install right. I read
        the
        installation guide backwards & forwards, with no help. I finally
        asked
        the "GURU" and he said " oh, that option is listed in the
        release-notes!!

        --
        Paul Cartwright
        Registered Linux user # 367800
        Registered Ubuntu User #12459
        http://usdebtclock.org/

        _______________________________________________

        Ale mailing list
        Ale at ale.org
        http://mail.ale.org/mailman/listinfo/ale
        See JOBS, ANNOUNCE and SCHOOLS lists at
        http://mail.ale.org/mailman/listinfo

-- 
-- 
James P. Kinney III
Actively in pursuit of Life, Liberty and Happiness 
Doing pretty well on all 3 pursuits    

 Faith is a cop-out. If the only way you can accept an assertion is by
faith, then you are conceding that it can’t be taken on its own merits.
   Dan Barker, "Losing Faith in Faith", 1992 

_______________________________________________
Ale mailing list
Ale at ale.org
http://mail.ale.org/mailman/listinfo/ale
See JOBS, ANNOUNCE and SCHOOLS lists at
http://mail.ale.org/mailman/listinfo

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.ale.org/pipermail/ale/attachments/20100708/bdd0f51f/attachment-0001.html 