Documenting installers? (Take II)

[Geoff Hart <ghart -at- videotron -dot- ca>]

Brian Jennings and others have critiqued my simplistic description of 
an installer documentation:
"So your installation instructions can be as follows:
1. Things you need to know or do before installing
2. Options to think about before you run the installer.
3. Put away the manual and run the installer."

<<In principle I completely agree. However, in my case I am documenting 
an install of a product that can be networked and [this approach]... 
does not work as well for the network installation.>>

It should. Please note that I prefaced my suggestion with the statement 
that the installer itself must be sufficiently well written that it 
explains all the key points as you go through the installation process. 
The first two steps (above) only prepare the reader to begin the 
installation, as follows:

After step 1: They now understand the context and the application, and 
know whether they have all the tools, system resources, training, etc. 
that they require to successfully perform the installation. This way, 
they don't even launch the installer until they thoroughly understand 
what they will shortly attempt, and have gathered all the necessary 
tools (physical, metaphysical, and other) to proceed.

After step 2: They now have done all the thinking necessary to 
understand the various options that will be introduced by the installer 
software. In theory, there should be no need to stop the installation 
and spend an hour figuring out which option they should choose because 
they've already researched and made that decision.

Think of it this way: Steps 1 and 2 prepare a blueprint and list of 
materials for building a house. Step 3 (running the installer) is the 
actual construction of the house. No reputable builder proceeds without 
first obtaining a blueprint or creates the blueprint as they go in the 
vain hope that it'll work. Why would someone installing complex 
software be any different? It boggles my mind that so many programmers 
still build software without such advance planning (or worse yet, 
abandon their plans as the project progresses), but I guess that's why 
they call programming an art, not a science.

<<If I must provide external documentation on any part of the install>>

The problem with documenting installation steps is that this is a 
1970s-era approach to computer documentation that has survived into the 
modern age. Way back when, there were no installers like the ones we 
use nowadays, so it was necessary to describe the installation process 
in excruciating detail. (Trust me on this... I worked briefly on the 
team producing System 38 installation/migration utilities for IBM in 
the mid-1980s.)

A modern installer can easily be written well enough to eliminate the 
need for external documentation--if the developers are willing to spend 
the time doing so and work with you to come up with clear onscreen 
instructions. This approach recognizes that help files and printed 
documentation are necessary only when you can't build this assistance 
into the interface itself ("embedded help"). What's missing even in 
modern installers is the guidance for users who must think about their 
choices _before_ they begin the installation. That's the problem my 
suggestion addresses.

--Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo