Re: Tradition of unreadable documentation
- From: Peter Moylan <peter@xxxxxxxxxxxxxxxxxxxxxx>
- Date: Mon, 10 Apr 2006 13:29:07 +1000
Richard Maurer wrote:
Peter Moylan wrote:[...] and there's also a tradition in the **ix community of making
documentation unreadable.
That leads to an interesting question about how such communities
propagate themselves. I certainly agree that while the documentation
was correct, the terseness nearly always left questions unanswered.
Whatever the answer to that question, one thing is clear: once a
tradition is established, nobody in that community can see the flaws in
that tradition, so the same style is perpetuated forever. At least it's
consistent.
Years ago, my standard test for the user-friendliness of an OS interface
was to see what would happen if you typed "help". Today almost all
systems fail that test.
Of all the operating systems that I've had to use, several really stand
out in my mind, probably because they're the ones I've most recently used.
1. Unix was developed in the belief that computers would only be used by
experts, so the help system is designed on the assumption that you
already know all the answers, and only need reminding about the
definitions of all the cryptic parameters.
2. Linux is based (by an indirect route) on Unix, so the help system is
Unix-like except in one respect: a lot of the development was done by
the sorts of students who believe in adding the comments after the
program is written, so most things are simply undocumented.
3. MS-Windows comes from a company that believes that advertising is
more important than utility. The help system is very impressive. If
you ask for help on a particular feature, you get a long description of
why that feature is the best thing since sliced cheese, and the great
advantages of using that feature. The only part that is missing is any
information on how to use the feature.
4. I use eCS these days, and eCS is a descendant of OS/2, which was
developed by IBM. Now, IBM believes in very detailed documentation, so
no matter what question you have you can be sure that the answer is
somewhere in the hundreds of thousands of pages of manuals. The only
catch is that a lot of guesswork is needed to know which manual should
be consulted, and how to get to the information without having to read
the entire hundred pages of each manual. Well, there is one more catch:
some of those manuals are company confidential, so you have to know an
insider to get any answers. On the positive side, things have improved
a bit since IBM lost interest and handed over the operating system to
somebody else. Now all the application documentation is provided by the
program authors, who invariably put the documentation into the same
directory as the software, i.e. manuals no longer live in the directory
dedicated to holding lots of manuals with cryptic names and unknown
function.
--
Peter Moylan http://www.pmoylan.org
Please note the changed e-mail and web addresses. The domain
eepjm.newcastle.edu.au no longer exists, and I can no longer
reliably receive mail at my newcastle.edu.au addresses.
The optusnet address still has about 4 months of life left.
.
- References:
- Thinking about getting a newsreader to block D. Spencer Hines
- From: matthewshepherd
- Re: Thinking about getting a newsreader to block D. Spencer Hines
- From: matthewshepherd
- Re: Thinking about getting a newsreader to block D. Spencer Hines
- From: Peter Moylan
- Tradition of unreadable documentation
- From: Richard Maurer
- Thinking about getting a newsreader to block D. Spencer Hines
- Prev by Date: Re: Thinking about getting a newsreader to block D. Spencer Hines
- Next by Date: Uncivil incivility
- Previous by thread: Tradition of unreadable documentation
- Next by thread: Re: Thinking about getting a newsreader to block D. Spencer Hines
- Index(es):
Relevant Pages
|
