From: ophof@SERVER.uwindsor.ca (Scott Ophof)
Newsgroups: news.software.readers
Subject: Re: FAQ's and how to get people to read them
Date: 28 Jan 1993 17:40:55 -0600
Organization: UTexas Mail-to-News Gateway
NNTP-Posting-Host: cs.utexas.edu


On 23 Jan 1993 09:28:01 GMT dls@Autodesk.COM (Daniel Louis Smith) said:
]        I usually read FAQ's in the areas I'm interested in before posting,
]and encourage those around me to check them out.  I personally get irked
]by the ones that do not have all of the questions listed at the beginning.
]These remind me of an Easter Egg Hunt :-)

Personally I can accept up to one screen of introduction.  Anything
more results in my hitting the "next-item" key (unless this is the
last and/or only source of info I have managed to find, and even
then I have to be pretty darn desperate!).

]        Any opinions as to what formats work best?  I can see how some
]lend themselves more to readability, and others to easier text processing.

Any format which gives priority to readability and understandability
is fine with me.  I couldn't care less about "pretty printing".
If it's easily understandable and well readable, then any print of
it should turn out just fine.
Note that "text processing"/"pretty printing" to me mean the version
literally PRINTED ON PAPER.

Assume the following example:

   uuencode and compres are too process you should use to get it
   to your friend.  Then he'll unship it, since he's a guru
   anyway.  ;-)

The above can be made readable, but no amount of "pretty printing"
will make understandable; typos, bad grammar, no sequencing or
explanation of the terms used, nor which words are commands...

The following setup however:

   Sending binaries by email:
      Due to all kinds of translations in email networks (and
      gateways between them) it is unlikely that a binary file
      (see note 1) will arrive unscathed at its destination.
      [...]
      such utility, and the even safer "xxencode" is another.
      To learn more about "uuencode" resp. "xxencode", type:

         man uuencode
      resp.:
         man xxencode

      See also the "ship" command.  (note 3)

   Receiving binaries by email:
      Binary files sent by email to you must be decoded before
      they can be used.  They might also have been compressed in
      some way.  (see note 2)
      To decode the mail file, one uses either "uudecode" or
      [...]
      When uncertain, it is best to make a copy of the file.
      Thus one can always retrace ones steps and start over.
      To learn more about "uudecode" resp. "xxdecode", type:

         man uudecode
      resp.:
         man xxdecode

      See also the "unship" command.  (note 3)

   Notes:
   1:  Executable files, in general any file containing characters
       not normally visible on-screen.  Any file processed by the
       [...]
       the lower and upper case alphabetics, the digits, and the
       period ".", comma "," and space characters.

   2:  The command "compress" will squeeze a file in some way so
       [...]
       To restore compressed files to the original, one uses the
       "uncompress" command.  To learn more about both, type:

          man compress

   3:  The commands "ship" and "unship" are each others' partners,
       and combine the "compress" and "uuencode" functions, resp.
       "uncompress" and "uudecode".  To learn more, type:

          man ship


This is IMHO much more readable and understandable.  Note that I
left out certain portions ([...]); it's the setup that's important,
not the whole text itself.  I just took an example off the top of my
head, so please excuse the verbosity and imagine it pared down to
the necessities withOUT also dropping related matters.
Also, I made up the "(un)ship" command...  ;-)

This setup also does not assume that some kind of "pretty printing"
(ie. on paper), or highlighting/underlining/etc. will be used.
In other words, just about ANY system in the world (Unix or not)
will be able to see this exactly as written, in print or on-screen.
BTW, anyone still assuming that the newsgroups are only read by Unix
users and on Unix machines is living in the stone ages.

Note also that I made one glaringly incorrect assumption; the reader
knows the computer on the other side is the same as the one on his
end where executables are concerned.  The point I'm trying to make
is that it's not fair to assume that users have "prior knowledge"...


Here's a suggestion for a setup of "news.answers" (misleading, non-
intuitive name imho..) that I might find acceptable (using the "trn"
commands).  An important note is that I would find it exhasperating
if after having viewed an FAQ, it would not be accessible later on.
Thus *any* items in "news.answers" must *never* be killed or even
killable.  I can accept "kill" to actually mean "hide", and have an
"unhide" command to restore hidden stuff to visibility.

Typing:
   g)o news.answers
results in the following display:

   1     alt.
   2     comp)uter.
  ..     ...
  12     rec)reation.
  13     soc)ieties.

Ie. a display of the first level of the newsgroup hierarchy.
Either:
 - Typing a number and <return>
 - The first unambiguous letters of the group name and <return>
 - Tabbing (or cursoring) to the relevant line and <return>
will invoke a display of the next level of the selected group.
This process can be continued in nested fashion till "there ain't no
more", in which case one is shown the FAQ for that group.
Note:  Invoking "hide" would remove a line from the screen, but NOT
readjust the numbering.  Thus one can immediately see which groups
have become hidden, and recover them when necessary.
If the user knows the name of the subgroup he wants, it should be
possible to go to the relevant line and append that subgroup's name
to the text already displayed.  Thus, if I want to see the FAQ on
"soc.culture.usa", I should be able to either:
 - Type its number and ">",
 - Type the first unambiguous letters and ">",
 - Tab to the relevant line and type ">",
then type "culture.usa", hit <return>, and see the correct FAQ on my
screen.

Also, typing:
   /keyword/     (like "elm", case INsensitive!)
or:
   /groupname/   (MUST include a dot ".")
would display either a list of whatever groups there are with that
string in its name, or the relevant FAQ.

The FAQ itself should be a continuation of this concept; ie. item 0
would be the intro item (which in itself could be a nesting...).
The questions are what one would see on the first menu level of an
FAQ, and each question could have sublevels...


Backing out:
Of course one should be able to back out level-by-level, but also
back out "n" levels (something like "3q" to backout 3 levels?).
Leaving the whole thing in one shot should be possible, both as
"forget I was here", and "remember what I defined as setup".

A "Where-Am-I?" facility would be very nice for navigation;
sort of like the "thread" displayed in the top right corner of
"trn".  One could thus go from any level to anywhere else in ones
own setup of "news.answers"...  :-)
This would save a LOT on backing out and plunging in again!
Of course "g)o somewhere" should be implemented for those who know
exactly (or near enough) what they are doing.


Alternative primary initial displays (selectable as an option and
from within the newsreader):
1: Display ALL the groups, and allow the user to hide those he's not
   (currently) interested in.
2: Implement a "D)isplay" command which when typed against some
   group name (at any level) will display all groups "under" that
   name as a tree, and again allow "(un)hiding" of any groups thus
   displayed.  The numbers for such lines could be something like
   "nn.mm", with "nn" being the number of the original line the
   "Display" command was typed against.  Allow SAVING of this setup
   so the user can have his own custom-made "help" facility, of
   only the stuff *he* is interested in.

Is there anyone who has read this through to the end?  ;-)


Regards.
$$\    F. Scott Ophof

--------------------------->  I speak *only* for *myself*  <-----
My credo:  Computers exist for OUR benefit, NEVER vice-versa.