The Arcade BBS/arcadebbs.zip/arcadebbs/TEXT/DOCUMENT.TXT

Text File | 1993-07-07 | 6.0 KB | 113 lines

     Computer Documentation is a diverse entity, but an important one.
Despite our attempts to avoid it, we find ourselves continually drawn to
computer documentation, whether to look up the meaning of a "Diagnostics
Fault Error" or the location of a coprocessor socket on a 386 motherboard.
Although all computer documentation is computer-related, two documents can
be remarkably dissimilar.  Sometimes, documentation can actually be fairly
competent, and information can be acquired with a minumum of effort.  Far
too often, however, we are driven to the point of seeking out the authors of
the documentation and strangling them.
     If there is one thing alike about all forms of computer documentation,
it is that they can all be classified into a few basic categories.  These
categories are detailed in this file, and I hope that the reader, upon
browsing this information, will be able to correctly identify (and burn)

                 THE MANY TYPES OF COMPUTER DOCUMENTATION

                               by  Octavian
                        SysOp: The Spearpoint BBS
                               410-889-5156

(AUTHOR'S NOTE: A "Cheap Plug" document is one that contains a really
desperate BBS plug.  This file is a perfect example.)

The "Microsoft Documentation"

     Although it might seem, at first, that the phrase "Microsoft
Documentation" applies only to documentation written by Microsoft, it actually
applies to any computer documentation that incessantly refers to itself.
     An example: "To activate the preselector, turn on your preselector by
selecting an icon to preselect.  This will preselect the icon.  If you wish
to preselect another icon, preselect the file window.  These preselections
are various preselections that allow you to preselect other preselections."

The Japanese Documentation

     "Japanese Documentation" is not written in Japanese.  Rather, it is a
word-for-word translation of documentation that was once written in Japanese.
For some reason, companies cannot seem to hire American translators to write
new material.  Instead, they must hire Japanese translators who are only
loosely familiar with the english language, and the result is usually
disastrous.
     An example: "You push button Go, push more.  This after push you push,
go push step 1 you.  Comment on push button go, push more go comment one to
three.  One is go you when you push button, two is go where are other buttons
and you push too."

The Idiot's Documentation

     Clear, concise, and explicit documentation is a must.  However, there are
some people who insist on taking this medium to the extreme.  Such instances
tend to insult the computer-literate and bore even the most computer-
illiterate users.
     An example: "Type in "CD\", without the quotes, and then hit the enter
key, which is the large key with a curved arrow printed on it.  The diagonal
line following the letters C and D is a backslash, not a normal slash.  The
backslash key is usually the key with a slash on it, and a little line above
the slash, NOT THE KEY WITH THE QUESTION MARK ON IT."

"Grammar?  What's that?" Documentation

     The example speaks for itself:
     "Seletc the therd option, 'Edit.  And click  thr mouse.pres EN?TER to
selct the optiones,make suar to illeusidate the hylite.and pres "s' to savw."

The "Who do you think I am?  Bill Gates?" Documentation

     Often, documentation is written for "the people who really know a lot
about computers."  This is often done for a reason; for instance, the program
in question could be targetted mainly at such persons.  However, problems
arise when documentation is written by such computer-literates.
Unfortunately, it seems, these computer-literates tend to assume that everyone
knows just as much about computers as they do.  Of course, to anyone with a
life, such documentation is difficult to understand.
     An example: "WARNING: Make sure that your 074893AB switch is set to
reinstate your IRQ-M4 integrator upon a VTN Mode 7 search.  Once the selector
is at the approprate level, reinstall your TS817 drivers, making sure to
avoid unnecessary KTL conflicts.  Then, reintegrate your Modem Conjugation
Package, and set your 03 activator dial to the DLC-T settings.

The Incomplete Documentation

     The authors of this form of documentation, for one reason or another,
assume that the people who are going to be reading the manual already know
exactly what they're doing, and use this as an excuse to leave out crucial
points of information.  In many instances, incomplete documentation will not
provide information on what a given error message means, what to do if such
an error occurs, or why that error occurred in the first place.  Instead,
the documentation refers you to a "customer support line" that is open from
10 am to 3 pm Monday through Thursday, and is long-distance.  Further, such
documentation tends to spend large amounts of time explaining frivolous and
useless features that you couldn't possibly ever have a use for.
     An example: The entirety of the Windows manual.

The Well-Written Documentation

     This, unsurprisingly, is the rarest form of computer documentation.
Well-written documentation tells you exactly what you need to know, and
exactly why you need to know it.  Well-written documentation is clear and
concise, but not overly so; well-written documentation is grammatically
correct and easy to follow even for the layman; well-written documentation
is comprehensive; and well-written documentation does not ask you to go to
great lengths to acquire information that could have been painlessly delivered
had the authors not been stupid.
     An example: None known.

And so our study of various forms of computer documentation comes to a close.
If you're planning to write documentation for a shareware program or a
Microsoft program, pick any of these forms at random, and work from there.
If, by some fluke of modern understanding, you choose "The Well-Written
Documentation," pick again.

                                        ---Octavian