TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:How do you help clients install software? From:Geoff Hart <ghart -at- videotron -dot- ca> To:TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, John Cornellier <jcornellier -at- abingdon -dot- oilfield -dot- slb -dot- com> Date:Wed, 18 Jan 2006 10:22:16 -0500
John Cornellier wondered: <<We are reviewing the documents we include
to help deploy a software product. Ignoring such post-installation aids
as... [deleted list]>>
Good thought. Installation should stand apart. If your installation
software doesn't provide the necessary information onscreen, close at
hand during the installation, you need to reconsider your choice of
software. (Of course, it may be the only choice... don't recall seeing
a "help" or "more info." button in an installer. Do the installer-maker
programs such as Wise allow for this kind of sophistication?)
<<I wish to focus on: - release notes / readme>>
Again, these should be part of the installer. If you've got time to
write them, you've got time to integrate them in the installer. I know
this isn't commonly done, but that's poor planning and a lack of
concern for the user, not "best practices".
<<- installation guide (could be broken in two: quick start + admin &
config. guide)>>
Why not make this part of the installation? Step 1 in the installation
should lead the installer through a quick process of analysis: Do I
have everything I need (disk space, knowledge, etc.) to do the
installation? If not, where can I get the necessaries?
Again, this isn't often done, but that's laziness, not careful thought.
Why ask someone to go spelunking in Windows to find out if they have a
specific DLL required (per the release notes), when it's trivial for
the installer to check whether the right DLL version is present and, if
not, offer to download it from the manufacturer Web site? Better yet,
put it on your installation CD! Ditto for graphics drivers, database
components, and on an on.
The purpose of an installation process is twofold: First, tell the user
everything they need to know to determine whether they can or should
proceed. Second, hold their hand throughout the installation, and give
them all the support they need during the process. Why don't we write
online help for installation software? Beats me!
<<- anything else e.g. install wizards, CD blurbs, download
instructions, etc.>>
Download instructions are a pre-sale device, and nobody wants to read
CD blurbs. Don't know about you, but I go out of my way to avoid
reading installation instructions... 30 seconds skimming the
readme.txt, then I dive right into the install and only go back to that
file if something looks wrong. I doubt most people are any different.
That means you should be relying on the install wizard to get things
right, not forcing the user to do this work. Aren't computers supposed
to make our lives easier? We're not here to make things easier for the
software, after all.
<<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. >>
The one group that's significantly missing from this list? The users.
Your support department will provide some useful advice, and Marketing
may (if they actually polled your users rather than simply making
assumptions about them), but why not go direct to the source? They'll
tell you exactly what those docs are supposed to do... you just have to
ask them.
<<E.g. some people think that the release notes are a kind of
quasi-marketing brochure which trumpet the new features>>
That's a load of fecal matter. If someone has already bought the
software, they either already know about the new features (that's why
they bought it!) or they don't care.
<<Others (including me) think the release notes should be a "warts and
all" late-breaking document including known bugs and workarounds.>>
That's my preference... as a user, not as a theoretician. The goal of
creating an installer is to install the software successfully--not to
test how good the user is at assembling a batch of cryptic "oh yeah, we
forgot to tell you..." details in the readme file.
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