Incomplete preliminary manuals

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 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
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html