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.
I'm currently tasked with writing an installation guide
for a Windows software development kit. The SDK comes
in different flavors and runs under Windows 3.1x, Windows NT
and Windows 95.
The programmer has written a sophisticated install
program that detects which environment you are running and
whether various ancillary software has been installed (and if
it hasn't, installs it). The install program has about 8
screens. We worked on the text for the screens together, so
they're not too bad. The first screen (Welcome) provides
high-level info about environments other stuff the user
needs to know. Some of the remaining screens require that
the user provide configuration-related input, such as
paths, hostnames, and port numbers. Others are informational.
The screens are clearly written and also have on-line help.
My problem in writing the install guide is that I can't
decide how much information I need to provide in the
written guide, given that the screens and on-line help
provide alot of information. It feels silly
to include screen dumps with steps that say "Type the
hostname and select continue" when that's totally
obvious from the install program.
There are, however, those 3 screens where the user has
to input information. The folks using this install
program are (theoretically) sophisticated users (they're
programmers), and shouldn't need hand-holding on how to
specify a path or what a hostname or port number is.
I thought I would explain how to start the Install program
and then do a road map or flowchart type-of-thing
showing what happens in the install and provides sidebar info
on the user input steps. This approach would give the user
an easy-to-read overview - a presentation of the information
that's different from the install program - and clarifying
information on the user input steps.
Anyone have any other ideas on how to make the printed
doc useful yet non-redundant?