Re: Why newbies don't RTFM...
From: Netocrat (netocrat_at_dodo.com.au)
Date: 09/26/05
- Next message: Jacob: "Re: cp -r /* /local/backup"
- Previous message: Unruh: "Re: cp -r /* /local/backup"
- In reply to: Rick Moen: "Re: Why newbies don't RTFM..."
- Next in thread: Rick Moen: "Re: Why newbies don't RTFM..."
- Reply: Rick Moen: "Re: Why newbies don't RTFM..."
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Date: Tue, 27 Sep 2005 01:13:27 +1000
On Mon, 26 Sep 2005 01:09:11 -0400, Rick Moen wrote:
> Some of us involved in Linux documentation have tended to get a little
> cynical over requests for documentation "tweaks".
It seems similar to trying to fix an intricate bug - easy for someone to
suggest a fix that breaks something else.
[...]
> Moen's Law of Documentation: "The more you write, the less they
> read."
[...]
> Thus, greater conciseness often does much more good than do longer &
> more detailed explanations. Or, what might be needed is better
> indexing, or following the classic journalist's inverted pyramid
> format (http://mtsu32.mtsu.edu:11178/171/pyramid.htm), or the short
> answer / long answer format I often use -- or just a polite suggestion
> to Read The Friendly Manual.
All good suggestions.
> Naturally, there is a place for more-accessible documentation -- but
> there might just be a need for people to have better access to what
> already exists.
Yes, it's a good idea not to duplicate resources - except for development
that relies on it for testing alternatives.
> There are entire projects devoted to that already, e.g., the "Newbieized
> Help Files" at http://www.justlinux.com/nhf/ . I personally don't care
> for those (to digress slightly, for a moment), for several reasons:
[all sensible].
> But there are other projects.
The current projects that inspire me most are those that do what Linux/OSS
is strong at - interoperating and converting between formats. That's why
I mentioned KDE's help browser as doing a great job of integrating man,
info and KDE help pages. ESR's tool to convert manpages into DocBook
format also seems like a good idea. I read that many of the LDP HowTo's
are stored in this format too. It seems ideal for help documentation
because it is renderable in many different forms - PS, PDF, HTML, etc - as
well as being semantically tagged - understood by programs as well as
human readers - which makes it possible to tweak the documentation display
based on the user's skill level/requirements without the need for a
separate set of "newbie-centred" documentation.
[...]
> If someone says to me "I don't _want to understand_ what I'm doing; I
> only want to know [foo]", then I can sympathise with that, but there are
> other people I'd rather assist in the limited amount of time I have for
> entirely volunteer activity. (I'd rather help people who I expect will
> make meaningful contributions to the technical community in the future.)
That's practical as well as altruistic and probably explains a lot of the
attitude that leads to some c.o.l.m posters' disinterest (to put it
mildly) in any focus on unskilled users who don't intend on skilling up.
[...]
-- http://members.dodo.com.au/~netocrat
- Next message: Jacob: "Re: cp -r /* /local/backup"
- Previous message: Unruh: "Re: cp -r /* /local/backup"
- In reply to: Rick Moen: "Re: Why newbies don't RTFM..."
- Next in thread: Rick Moen: "Re: Why newbies don't RTFM..."
- Reply: Rick Moen: "Re: Why newbies don't RTFM..."
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Relevant Pages
|
