RE: How do you help clients install software?

["Joe Malin" <jmalin -at- tuvox -dot- com>]

Ahem...

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
starts
* Automated post-install configuration tasks
* Logging and reports
* command-line options for network-based/unattended/default/script-drive
installations
* hidden commands for overriding prerequisite checks, etc. so you can
test

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
(408)625-1623
jmalin -at- tuvox -dot- com 
www.tuvox.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,
etc.

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! http://www.webworks.com/techwr-l

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.componentone.com/TECHWRL/DocToHelp2005

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

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
http://www.techwr-l.com/techwhirl/ for more resources and info.