Incomplete preliminary manuals

Subject: Incomplete preliminary manuals
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Wed, 2 Apr 1997 10:09:37 -0600

Melonie Holliman asked for suggestions about shipping an
incomplete, preliminary manual with a software product
because the full manual won't be available for some time.

By curious coincidence, that's exactly what I'm doing right
now. After much nagging, politicking and other devious
means, I managed to start FERIC well on the road to a
formal software development and documentation process...
and equally importantly, I'm deeply involved early on. The
developers have even taken my advice on certain interface
issues. Yay! (Thanks again to all those who provided advice
on this issue last year. My article on the topic should
appear in _Intercom_ early this summer.)

Some context: FERIC is relatively new to the software
development business, and not very typical... we're no
Microsoft, that's for sure! We have a very small number of
clients (about 100 companies) that fund our research, and
we've worked closely with most of them for more than 20
years... so we know them very well in terms of their needs
and their other main characteristics as an audience.
Because of this small audience, the developers plan to do
personalized installations and demonstrations of most early
copies of the beta software while they're out in the field
doing their research; subsequently, we'll follow a more
typical mail-out-the-disks-and-hope approach.

The beta release of our software is formally available late
next week, and the developers are now reviewing what I'm
calling the "beta version" of the manual. The text goes for
French translation tomorrow (user interface already
translated). The text is short enough that it'll be back in
time for layout and distribution.

In the beta manual, I'm including who to call for help and
to report bugs, installation instructions, troubleshooting
tips for currently known problems that are outside our
control, a complete description of what the software does,
the "metaphor" for how it achieves this purpose, brief
descriptions of all menus and icons, the sequence of tasks
you must follow to work with the software, and who to call
(me!) to suggest changes to and improvements in the manual.
I even added a reminder in the middle of the hardware
requirements section (re. hard disks) that users should
make backups of their data. (Thanks, George... great idea!)

In effect, I'm doing a usability test and beta test of the
manual itself, and spending the summer developing the real
thing. Based on the feedback I hope to collect, I'll be
producing a revised, more complete manual by September.
I've included a reader-response form and postage-paid
envelope with each copy of the manual, but I'm not going to
be purely passive: because we have such a close
relationship with our clients, and so few beta testers, I
should be able to follow up with most of them (and perhaps
all) over the phone. In the meantime, I'll be producing a
skeleton of the online help that will accompany the later
versions of the beta software (bug fixes etc.), and asking
for feedback on that too. Final online help (complete with
all details... groan) should be available in September too.

My goal (based on our first guess--to be confirmed--at how
users will work with the software) is to put almost all the
reference information online, and put only the general,
overview information on paper. I can get away without
including much detailed procedural/reference information in
the early beta manual because of two things: the use of
these beta copies will be demonstrated to the client, and
the underlying model for the software is easy to learn and
use because it so closely matches the way our clients work.
Thus, the manual will provide the cognitive tools to work
with the software, the field visits will provide some of
the details, and the final manual and online help pwill
include the details that the users need to put the
cognitive tools to work: nails for the hammers to work on,
as it were.

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: Speaking for myself, not FERIC.

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: First job/warning signs
Next by Author: Tracking bugs
Previous by Thread: First job/warning signs
Next by Thread: What'sThis help

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

Sponsored Ads