Why We Need Good Software Manuals

Subject: Why We Need Good Software Manuals
From: William=E -dot- =Newkirk%Pubs%GenAv -dot- Mlb -at- RODES -dot- CCA -dot- ROCKWELL -dot- COM
Date: Tue, 30 Jan 1996 09:09:52 EST

>Date: Mon, 29 Jan 1996 09:43:42 -0500
>From: "Huber, Mike" <Mike -dot- Huber -at- SOFTWARE -dot- ROCKWELL -dot- COM>
>Subject: Re: Why We Need Good Software Manuals

>I was out at a training class (not about writing - I was the only
>writer there) and the guy at the next desk, out of the blue, started
>complaining about Microsoft manuals that have exactly the same
>information (down to the examples) as the help screens.

>In my experience, readers (except for the odd ones who read the
>manual before jumping into the software) have already searched the
>help by the time they open the manual. The reader wants
>something more, or at least a different angle. Basically, when the
>manual is open, the help has failed. Your coordinates are wrong -
>do not fire again.

yes! and one other thing i would expect to find in a manual are descriptions
of what are the valid choices and what values are OK. I'm always upset over
finding out there's some undocumented switch or initial condition value
that's not explained anywhere but exactly helps a problem get solved.
Especially when you have to call tech support and they cheerfully say "You
need to add the line popeye=sailor in the INI file and use the /mxyzptlk
switch with the value of ptooie and you'll be able to save your work to your
local drive next time."

makes one want to disassemble the code just to see what else might come to
the surface.

There are certainly going to be "undocumented" things left in software from
testing and prototyping that are going to be missed or overlooked. But that's
no reason to not have everything that's intended to be "OK to use" called out
in the book along with some description of how it gets used and what effects
are supposed to be intended by the values permitted.

If software was a physical box, not describing all the gozintas and gozoutas
would cost sales and increase warranty claims. Folks would claim and could
point to serious deficiencies in the software - "you didn't say pin 36 on
that connector was 12 kV!"

If the big boys don't think it's useful or worthwhile to put in a book, then
it should be on a web page or ftp site someplace for those who could use it.

one problem we're seeing with new stuff, is "pointless help". got a dialog
box with a field that says "file name" and an OK function button and you
click the help key and get a nice dialog that says things like "this is the
file name field". no duh. Nothing like doing the equivalent of using a word
to define itself. This seems to be coming from the development tools that
permit a developer to punch out a skeleton of a program easily w/o requiring
any underlying structure (programmer/developer gets busy fixing up the
program and forgets about those things put there by the "wizard" tools.)

bill newkirk
wenewkirk -at- rodes -dot- cca -dot- rockwell -dot- com
rockwell avionics/collins
general aviation publications


Previous by Author: JOB POSTING: Boise, Idaho
Next by Author: Re: FYI: Re: Re. Certification rebuttal/follow-on
Previous by Thread: Re: Why We Need Good Software Manuals
Next by Thread: Re: Why We Need Good Software Manuals


What this post helpful? Share it with friends and colleagues:


Sponsored Ads