TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
