Documenting installers? (Take II)

Subject: Documenting installers? (Take II)
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 20 May 2004 13:02:38 -0400

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!

From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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 for more resources and info.

RE: Documenting installers?: From: Brian Jennings

Previous by Author: Documenting installers?
Next by Author: Standardizing on XML? (Was: Re: Why WYSIWYG for XML???)
Previous by Thread: Re: Documenting installers?
Next by Thread: RE: Documenting installers?

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

Sponsored Ads