RE: How do you help clients install software?

Subject: RE: How do you help clients install software?
From: "Joe Malin" <jmalin -at- tuvox -dot- com>
To: "John Cornellier" <jcornellier -at- abingdon -dot- oilfield -dot- slb -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 18 Jan 2006 10:45:58 -0800


I limit Release Notes to the following, in priority order:
* New features for a revision/new release
* List of bugs fixed
* List of known bugs, including workarounds
* Known limitations and incompatibilities for particular platforms
* Upgrade instructions
* Documentation changes that couldn't be included otherwise

So I agree with you. Your audience may or may not read release notes,
depending on the type of product and the history of providing release
notes. The ordinary consumer probably has no idea what release notes
are, and doesn't read them. I read them for every piece of software I
get, but then I *know* what they are.

I always provide an installation guide. It may contain administration
and configuration, again depending on the audience. For enterprise-level
software, the same audience usually does installs and administration,
but may not do configuration.

CD booklets/blurbs/whatever are, IMHO, somewhat useful. The poor
sysadmin that gets the CD may not see anything more than that. In your
booklet, *always* refer back to the main install guide. That way, the
sysadmin will know it exists!

Download instructions are useful, but of course they are also worthless
if you need download instructions to download the instructions!

Install wizards are the best. I think they should include:
* integrated, context-sensitive online help
* automated prerequisite/compatibility checks
* automated configuration, whenever possible
* Detailed on-screen instructions
* Summaries of required disk space that appear *before* the installation
* Automated post-install configuration tasks
* Logging and reports
* command-line options for network-based/unattended/default/script-drive
* hidden commands for overriding prerequisite checks, etc. so you can

I've been in the SW business for 30+ years. The most underappreciated
and ignored part is software installation. I will venture a guess that
50% of all tech support calls could be avoided by an install that
prevented conflicts and tested itself for proper operation.

Unfortunately, writing the installation software is a task usually given
to the most junior engineers. Nobody wants the job because it's
considered to be a dead end, unrewarded position.

Joe Malin
Technical Writer
jmalin -at- tuvox -dot- com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.

-----Original Message-----
From: techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of John Cornellier
Sent: Wednesday, January 18, 2006 2:15 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: How do you help clients install software?

Hi all,

We are reviewing the documents we include to help deploy a software
product. Ignoring such post-installation aids as user manuals, reference
guides, bug trackers, training, and support, I wish to focus on:

- release notes / readme
- installation guide (could be broken in two: quick start + admin &
config. guide)
- anything else e.g. install wizards, CD blurbs, download instructions,

I'm trying to reach a consensus among various interested parties - tech
writers, testing, marketing, support, deployment engineers (the guys who
burn the CDs and check the target operating environments).

There is not much agreement on what these docs are actually supposed to
do. E.g. some people think that the release notes are a kind of
quasi-marketing brochure which trumpet the new features, and are used by
prospective clients to decide whether to upgrade. Others (including me)
think the release notes should be a "warts and all" late-breaking
document including known bugs and workarounds.

So I'd be grateful for any pointers to some kind of working definition
of the components of deployment support documents, or any random
thoughts on the subject.


Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: CD-Rs vs. Store-bought CDs (WAS: Do Burned CDs Have a ShortLifeSpan?)
Next by Author: RE: Can anybody tell me how, in FrameMaker, to easily find empty paragraphs?
Previous by Thread: Re: How do you help clients install software?
Next by Thread: Effective mechanism to gather end-user feedback

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

Sponsored Ads