Re: There's more to it than grammar

[Kenneth Mauro <kmauro -at- AMERITECH -dot- NET>]

John Wilson wrote:
>
(in part)

... Surely for most consumer
> (non-specialist) software products, the need of a manual is an admission of
> failure in this regard, or at least an indication of much room for
> improvement?

I think that "failure" is a strong word. Is Quicken an example of
non-specialist software? Should it need no manual? In my view, one
problem with documentation is that it focuses too much on the actual
keyboard/menu actions, and doesn't help the user enough with concepts
and explanation of the big pictures, or with more ideas as to how to
actually apply the software to MY project.

I wrote manuals for five years for a company producing CNC hardware and
the related software. Not once in all that time, was I ever able to
convince anyone in the tech writing group that we should be including
illustrations to show concept, overview, basic actions, etc. in order to
help the user get the "big picture." (Despite the fact that such aids
were routinely drawn on fancy copy-making marker boards when customers
came to headquarters for training.) Admittedly this was not what you
would call a non-specialist product, but I think the same ideas apply.

In my own work with machines and process, I have often wondered why I
put illustrations and descriptions into the manual, when the shop could
putting much of that same information right on the machine itself. Might
sound a little impractical at first, but it's an untapped solution, I
think. I/O such as sensors and solenoid valves are always labeled, and
all controls (push buttons, selector switches, etc.) always have legend
plates to identify them but there seems to be resistance or reluctance
to placing other identification on the machine, even when those same
labels appear extensively in the documentation for the control logic. In
other words, we should put as much of the manual right on the machine,
and I hear John saying that the manual should be contained in the
interface, or evident to the user in some way, so that the manual's role
is diminished or eliminated. To do that, I believe, you have to give
users some conceptual starting points.

Side bar: One of the most troubling underpinnings of this kind of
omission is that many people have convinced themselves that "users don't
want to read anything." I simply don't believe that.

I find that I need a good overview when I'm learning something new; an
overview that approximates an experienced person introducing me to
what's going on, what's important, how things work. Beyond that,
consistent and careful labeling of the functions (menus and dialog, etc)
become critical.

Personally, I would rather see software manuals contain concrete
examples of how to do things than to explain how to do many discrete
operations step by step. Because, doesn't it always seem that the manual
falls short in helping you do what YOU want to do? In the CNC hardware
business, engineers and tech writers spend a lot of time on what are
called "Application Notes." How the product is actually applied by the
user in the field. Maybe there should be more of that in manuals for the
non-specialiast software.

You can go to any bookstore and find tons of books on Word, or Word
Perfect, or Excel, but they all pretty much tell you how to do specific
operations. How many books (manuals, really) are there with examples of
how to actually DO a long manual, how to expand a simple spreadsheet
into somethat that will work for a user's specific application, etc.
People spend a lot of time putting together FAQs on web sites; that's
nothing but anticipating user questions based on experience. The same
thing could be done with manuals, turning them into application guides
rather than instructions on which keystrokes will take you where.

Didn't mean to go on that long. Thanks,

Ken Mauro
Schaumburg (Chicago) IL

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=