NetNews Usenet Archive 1992 #19/NN_1992_19.iso/spool/comp/lang/c/12764

Internet Message Format | 1992-08-25 | 8.6 KB

Xref: sparky comp.lang.c:12764 comp.misc:3325
Newsgroups: comp.lang.c,comp.misc
Path: sparky!uunet!haven.umd.edu!darwin.sura.net!zaphod.mps.ohio-state.edu!caen!hellgate.utah.edu!lanl!cochiti.lanl.gov!jlg
From: [e-mail] (Jim Giles)
Subject: Re: Giles' Manual Mania (Was - Re: About the 'F' in RTFM)
Message-ID: <[e-mail]>
Followup-To: comp.misc
Sender: [e-mail]
Organization: Los Alamos National Laboratory
References: <[e-mail]> <[e-mail]> <[e-mail]> <[e-mail]> <[e-mail]> <[e-mail]> <[e-mail]> <[e-mail]> <[e-mail]> <[e-mail]>
Date: Tue, 25 Aug 1992 17:14:11 GMT
Lines: 147

Responses forwarded to comp.misc

In article <[e-mail]>, [e-mail] (fred j mccall 575-3539) writes:
|> In <[e-mail]> [e-mail] (Jim Giles) writes:
|> [...]
|> >Six of one ....  Whether the document is misunderstood or whether it's
|> >wrong, it's badly written - and that's the major problem.  If a document
|> >is persistently misread, then it's just as wrong as if it contained false
|> >information.
|>
|> This is not necessarily true.  It's rather like saying that the fact
|> that we continue to have any automobile accidents at all is evidence
|> that roadways and automobiles are badly designed.  [...]

Are you suggesting that the converse is true - that accidents are
evidence that roads and cars are NOT badly designed?  Stating that
all accidents are entirely and solely the fault of the driver is
as insane as stating that *no* accidents are the fault of the
driver.  Neither of these positions is analogous to mine.

What I said was that if a document were *persistently* misread, it's
certainly an indication of a problem with the *document* - especially
if there exist other documents which describe similar tools and which
*don't* engender persistent problems.

|> [...]                                       No matter what you
|> do, you can't protect the really bad driver from him/herself.

Yes, but when you see reasonably good drivers have a disproportionate
number of accidents on a given road or with a given car: that seems
to indicate problems other than the driver.  And, many accidents that
aren't blatantly drug (alcohol) related are from a combination of
causes which include *both* design and driver errors.  There's
plenty of blame to go around.  If a relatively simple design
change would prevent or reduce the severity of a *common* driver
errors it seems reasonable to make that design change.

Why are you so intent on deciding who to blame instead of deciding
how to correct the problem?  Yes, it's true that if you cut yourself
with an old fashioned straight-razor, it's your fault - you used the
razor incorrectly.  But, that doesn't mean the invention of the
safety razor (which is now nearly universal for shaving) is not
an improvement.  Even if *all* the errors made with the old design
were the user's fault, that *still* makes it advantageous to devise
easier to use designs.  Why do you oppose that?

|> [...]
|> Similarly, no matter what you do with the documentation set, you
|> cannot protect the poor, inattentive, or lazy reader from misreading
|> it.

Based on my experience, this statement implies that UNIX documentation
*induces* inattentive or lazy reading habits among otherwise competent
and intelligent users.  The `gotcha' rate and the "it's in the manual"
questions are higher in frequency for *all* classes of users - not
just the lazy or the incompetent.

You are right that this is similar to the automotive analogy: *commonly*
made errors could be considerably reduced or their effect considerably
limited if the UNIX interface and/or its documentation were improved.
The name of the game is improving user productivity, not fixing the
blame for why its sub-optimal.  If changing something reduces the
frequency or severity of error - do it.  A number of possible changes
to UNIX would do just that.

|> [...]
|> >I've used software products where the bulk of the users *preferred* to
|> >obtain and read the documents rather than asking the consultants.  I know
|> >this is a possible way to write software/documents.
|>
|> I'm curious.  What products are these, and just what is this
|> miraculous difference in the documentation?  [...]

The primary difference is the tool itself (I've seen editors, compilers,
programming languages, databases, etc. with these characteristics): the
features are independent of each other as completely as possible.  Further,
the primary function of the tool is simple, clear, and uneffected by the
options (if the use of options changes the *basic* character of a tool,
it's time to write a new tool).  These primary functions are clearly
documented - with examples.  Options are also documented with examples,
but unless the related functionality is needed, the user should be
able to get by just skimming the introductory line of each option
to get an idea what's there (this is one of the purposes of making
features independent).

Take an editor, for example.  More than 90% of the time, the only
features of an editor in use are inserting, deleting, moving text,
and moving the active location (the cursor).  These features should
be completely independent of how any other capability of the tool
works.  It is possible to make *productive* use of an editor even
if these are the only features you learn "by heart".  Experts are
merely users who've had need of various options often enough to
remember their form and function.  I've seen editors that took
15 minutes to learn to use *productively*.

A menu system, if present, *should* be just a form of interactive
documentation which leads you through the more arcane stuff (like
changing fonts) until you have learned the keyboard commands to
invoke the same functions.  Even without menus, the document should
be well ordered and contain worked examples to guide you through
this stuff.  Utilities which are entirely controlled by their command
line should be documented this latter way (they, by definition, have
no menus other than those built on top of them by a shell).

Finally, there should be a *subject* index of the document(s), not
just an alphabetic listing of the directives.  Option or utility
names (and often even their brief descriptions) don't contain all
the subjects that the option or utility is appropriate to.  Try
doing a `man -k slides' sometime: many tools that you *know*
are capable of generating film, slides, overhead projections, etc.
are not listed at all.  In fact, on my Sun workstation (which has
a number of such tools installed) I get: "slides: nothing appropriate".

I've used tools which are written and documented well.  From
experience at our consulting office, I can tell you that users
actually prefer the manual for tools like this.  They seldom
ask questions and few of those they do ask can be answered
straight from the manual.

|> [...]                                               By making the
|> documenation sufficiently simplistic and doing the same with the user
|> interface, this can certainly be achieved.  However, then you have the
|> problem of the total inability to accomplish what you need to
|> accomplish because you have a wall of cotton between you and the
|> environment.

This simplistic interface that you deride is actually responsible for
well over 90% of all your activity.  Most of the options will be used
perhaps only once in every few uses of the tool (if that often - if
they are used nearly every time it's appropriate to change the defaults).
These options are still available, they're just unobtrusive: you don't
*have* to know them in *detail* to use the tool for its default purposes.
That cotton wall is insulation, not isolation.

In fact, for the most part the UNIX tools are often *less* capable
than their better designed (easier to learn and to use) counterparts
elsewhere.  This is the primary cause of the success of windowing
environments on UNIX, they *hide* the crummy interface.  A well
integrated environment should be easy to learn while retaining
functionality.  UNIX was evolved in a haphazard way without any
attempts to integrate the various features into a coherent environment.
It works: sort of.  UNIX is rather like a car in which you *have* to
know the detailed function of the cigarette lighter in order to work
the transmission - even though you don't smoke.

--
J. Giles