Writing question

[Mike Salovesh]

Alyosha, you have pushed my hot button.  I was horrified when I read the
whole message that appears below: it's too long, it's too emotional, and
writing it kept me up all night. I claim fogiveness on the grounds that
I have been assembling my new, improved computer out of spare parts
without benefit of a manual.

"Alexey I. Fuchs" wrote:
>
> Please, do not offend programmers. You show a clear case of Wellerism.

Please forgive my ignorance -- or my aging memory! I don't know what you
mean by Wellerism.

> The market is overloaded with books on computers written by illiterate
> money-seekers.

You are absolutely right.  Before I buy a book, most especially a book
about computers, I take a very close look at those parts of the book
that deal with matters I learned elsewhere.  If the authors get that
part wrong, I don't wait to discover what else they have done badly. I
just go on to some other book.

> Work with the computers requires some effort. The user
> wants to make everything with one finger.

Maybe some users do.  I use a computer because it helps me get to my
objectives, which usually have nothing to do with computers as such.  A
computer is a tool.  When I get a new tool, I want to learn how to use
it with reasonable efficiency and maximum effectiveness in accomplishing
the work I try to do with it. Most original equipment manuals don't help
the end user learn to use the product.

> The fact that a system, or a
> program, or an application is made for the user does not mean that it
> is made for an idiot.

Of course not. The idiots do the marketing.

> If you want to drive a car, even with automatic gears,
> you have to _learn_ to do it, though it may seem very simple.
> Now, you complain you cannot _learn_ because the muddles are impenetrable.

No, I claim that I cannot learn what I need to know by reading the
manual that comes with the apparatus, the program, the tool I want to
use.  It's the muddles _in the writing_ that I find impenetrable.  So I
stop what I want to be doing and figure out what my new tool can do. I
explore long enough to have a good idea of how it works, and I try to
find its limits by asking it to do more than the item's wrapper
suggests. Several hours or days later, sheer trial and error leads to my
learning how to use two obvious and three obscure functions in the least
efficient manner possible.  Then, and only then, the producer's manual
becomes semi-intelligible, but only for those functions whose abilities
and limits I've already discovered through trial and error.

> I admit there are jerks in the field who don't care about how the
> documentation is written, but this is not the usual case with
> commercial products, for support costs much more than development.

And the companies selling the products find it easier and easier to bury
essential parts of the instructions in plain sight.  At the same time,
more and more companies charge extra for support service. Some only
accept calls for technical support during "normal business hours".  Any
thought that the policy might be as reasonable as it sounds disappears
when you discover that the normal business hours they're talking about
are measured by local time at their branch offices in Middle
Kabumdiddle.  They never tell you that it is customary in Middle
Kabumdiddle to abstain from doing business during any sabbath or other
sacred day in the combined sacred calendars of Christianity, Islam,
Judaism, Buddhism, Confucianism, and Bill Gates.

Yes, support costs more than development.  But not if you  give up
providing support.

> In good companies,  documentation is written by people who are        > specially trained for that.

That is exactly what we're talking about.  Unfortunately, there are very
few good companies.

> Take Microsoft as an example: they create profitable, user-friendly,
> easy to use crap, which, in fact, is not worth a penny. But look at
> the documentation: it is brilliant. The user goes crazy.

I admit that Microsoft's documentation is brilliant when used for its
purpose, which is to drive the user crazy.  After recovering, the user
is forced to try to use the software because it cost lots more than a
penny and it's impossible to escape being charged for it. It then turns
out that the software as provided lacks seventeen essential patches --
which Microsoft will provide when you purchase an "upgrade" whose only
purpose is to correct shortcomings that should never have been inflicted
on the public in the first place.

> The point is: just pay attention. Even if a programmer is not skilled
> in writing, his grammatically incorrect sentences are logically
> impeccable.

I will grant that may be true -- but the logic can only be understood by
people who speak all three of the extinct languages of Middle
Kabumdiddle.  Without that knowledge, it is very hard to know what
action is called for when the instructions say "off grass please be
staying away from unless in condition of A3".

> I beg your pardon, if I slide off the rail, but this issue is hurtful.
> And if I see a "computer genius," who writes "press button if not open
> window to double-click when scheduler process open dialog boxes," it
> pisses me off not less, for it is true that the program is even more
> unusable when it lacks documentation.
>
> The best manuals are written by the best experts.
> Best books for kids are not written by kids or even by
> writers-by-chance.
> Think of Jacob Grimm and J.R.R.Tolkien.
>
> Sorry again,
>
>                                                 A.Fuchs

Don't stop in mid rule!  The complete statement is "the best manuals are
written by the best experts, provided that those experts have taken the
trouble to become expert writers."

Which brings us back to my original question:

I wouldn't be happy if English majors with no training in computers
tried to create an operating system I would have to use on my computer.
Why should I be forced to accept the impenetrable muddles written by
computer geniuses with no knowledge of writing?

-- mike salovesh       <salovesh at niu.edu>      PEACE !!!