Multiple versions?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Rebecca Hopkins reports: <<I have a software installation manual that
requires multiple versions. This app server, that database, the other web
server, a different operating system - there are eight basic
configurations... Currently, Help is HTML Help with a book metaphor. I have
three versions of the install which have tremendous overlap... I was
thinking of taking that decision tree and turning it into a web of short
steps. This would be easier to maintain, but only easy to follow online -
impossible to print out.>>

What you really need is not an installation manual, but rather embedded help
in the installation software. Alternatively, truly context-sensitive online
help for the installer (not for the installed application) would also work
well. The installation software would provide basic help directly as part of
the interface (e.g., a field labeled "Select your server" with a browse
button) and more advanced help for only the currently displayed installation
screen. The fact that the overall online help contains details for all
possible configurations should never be apparent; users would only look at
sections related to the current dialog box in the installation.

<<the major problem I see with the multiple versions in one document is not
really the maintenance - that's what they pay me for - but the difficulty in
reading it. The user has to make a decision every couple of sentences if the
next section concerns him or not.>>

Again, this suggests that the help should be integrated with the task (the
installer) rather than presented as something standalone. Conceal the
complexity from the user! Each decision should limit the amount of help now
available so that only relevant help is overtly displayed.

Of course, they could always dig through the index and find irrelevant help
for other configurations, but given how hard it is to get them to use the
help in the first place, what are the odds? Most will just click the help
button, press F1, or open the help menu, and if the help is
context-sensitive, that should open the topic that describes the current
dialog box. If you can't finagle something like this with the programmers,
you could at least provide a help code as part of the dialog box: "For
detailed help on this dialog box, open the help topic entitled [name]",
where [name] matches the topic name and index entry you used in the help
file.

<<the last guy I heard about was a Cobol programmer. He followed every step
to the letter, including some that did not apply to his situation.>>

Which is a really good reason to ensure that nobody ever sees instructions
for steps that don't apply to what they're doing.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.