A user's commentary

[Arlen -dot- P -dot- Walker -at- JCI -dot- COM]

The following is an "anonymized" comment made by a user. The product in
question is FileMaker Pro, but that's not the point. I apologize to any
Claris writers reading this for seeming to single them out; that's not the
intention here. In the message the writer implies the same should be said
of *all* SW manuals, and in private correspondance with me the writer
bluntly asserted what this message only implies.

I'm reposting it here, after removing things like personal names and other
identifying references (and, BTW, after asking for and receiving
permission) as a reality check. Here's one user's real-life, right up
front, in-our-face, actual opinion of the state of manual writing today.
I'm not aiming to start any kind of fights here; I just want you all (and
myself as well) to take a look at what we do when viewed through the eyes
of another. How well are we serving our customers?

--------------------Message follows-------------------------------
I haven't programmed computers seriously in 20 years, but I see that
nothing has changed:

1.  Computer manuals are not written to explain anything:  They are written
to serve experts who already know everything about the software, and just
need some handy place to look it up.

2.  Computer manuals do not have a Chapter 1.  This is the chapter that
tells you, in plain English, what the software does, how it works, and how
to get started.  This chapter has been removed from the Filemaker Pro
manual, and something else was named Chapter 1.

3.  The manual does not have a single example that would be of use to
anyone in my business.  (This isn't limited to my business -- name any
business, and it doesn't have an example for it, either).

4.  Examples in the manual do not work on the screen.  It will just sit
there, unblinkingly, and refuse to do what it's supposed to do.  And you
can never figure it out by yourself.  Some expert will eventually stop by,
take one look at it, and say you shoulda added the framwitz variable to the
veeblevetzer, and every dummy knows that. (No, of course that's not in the
manual.  Manual writers always leave out one critical piece of information
for each function. It's their job.).

In anticipation of the arrival of my templates, I took an introductory
course in Filemaker Pro, which showed me how to browse, sort, find and all
that jazz.  I can now create and sort a name and address list.  Whoopee!
Anything more than that, I have to use the manual.  Shudder.

<signed>
Ex-NASA programmer (1960 and 70s).
Ex-Real-time computer system expert
Ex-Operating system and process control specialist

------------------------end of included message----------------------

Yes, the writer was harsh. But let's look at our work through these eyes
for a while. Is what we're writing really fitting the wants and needs of
our customers? Think about it.

Have fun,
Arlen
Chief Managing Director In Charge, Department of Redundancy Department
DNRC 224

Arlen -dot- P -dot- Walker -at- JCI -dot- Com
----------------------------------------------
In God we trust; all others must provide data.
----------------------------------------------
Opinions expressed are mine and mine alone.
If JCI had an opinion on this, they'd hire someone else to deliver it.