Re: Thoughts on RTFM
On Thu, Nov 29, 2001 at 10:46:15PM -0400, cmasters wrote:
| Greetings all,
|
| My recent difficulties with printer and mail setup have led to to the point
| where I simply must express my thoughts on "RTFM".
...
| Their are shortcuts, strange citations, symbols and references to
| structures that only make sense once Hebrew has ~been learned~. It
| becomes an excercise in circular reasoning.
...
| Do you see. No-one can possible be expected to ~read for comprehension~ a
| manual that has ~not~ been written with a ~complete~ newbie in mind.
Certainly there are conventions that are used by unix users, and it
certainly helps to know these when reading various manuals. There are
books (and I'm sure howtos or other docs) that explain the basics of a
shell, filesystem, and other conventions. However you don't want
_every_ manual written for the _complete_ newbie. If they were, they
would all have the same basic here's-how-you-turn-it-on,
here's-how-you-name-the-files, etc., etc., in them and that would
unnecessarily bloat the manual and make it a chore to find the real
information. Certainly complete newbies need some assistance to learn
the basics, but that should be in a dedicated document. Once you've
read a couple of howtos or manuals, you get a feel for how they read.
In addition, there is no better teacher than experience.
| In a previous response to email regarding my ongoing email problems,
| I made reference to the Mutt manual. Section 6.3 Configuration
| Variable is chock full of all kinds of variable that can be invoked
| through command line or the config file. The author(s) forgot to
| include any ~in context~ examples or to identify which of these
| variables requires the #$% ~set~ prefix. Ah well ...
If you note, section 6 is the _Reference_ section. References are
meant to be short and to the point without examples. They are
intended for those who know what they are doing, but need to refresh
their mind on a point or two. Also, section 6.3 is the _Configuration
Variables_ section, not the _Configuration Commands_ section (6.2).
All of them need "set".
| I actually fully support it (hence my
| refusal to cave-in and use M-crap).
That's cool.
| But somewhere along the line, bells and
| whistles should have gone off that all the configuring in the world WILL NOT
| HAPPEN without clear, concise, and comprehensible instructions/directions.
Isn't that what this list is for? (only semi-serious)
| Last words (for now) ... in order for Open Source to have continued and
| increasing validity, it ~has~ to mean more than just "change at will". It
| must include "if I've written the application, I will include ~clear~
| instructions".
True, but all of it is dependent on volunteer effort. If I like
coding and don't like writing docs, it is less likely that I'll spend
my free time writing docs than coding. It is also probable that my
docs are not very good. Also, every document needs an audience. If I
expect my audience to be well educated and understand common unix-ism
and/or conventions, then I will not explain them as if they didn't.
My perspective on who will be using my code also makes a difference in
the type and style of the docs I write.
After all this, I must admit that when I read through the procmail
manpages I didn't understand most of it. I did end up determining the
pattern that I should follow for the types of rules I write, and I
know that there is much, much more power there if I really want to
learn it.
-D
--
Microsoft: "Windows NT 4.0 now has the same user-interface as Windows 95"
Windows 95: "Press CTRL-ALT-DEL to reboot"
Windows NT 4.0: "Press CTRL-ALT-DEL to login"
Reply to: