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:Re: Getting Started guides From:sheldon kohn <sheldon -dot- kohn -at- MCI -dot- COM> Date:Wed, 3 Feb 1999 11:12:58 -0500
Hi Lynette,
In my opinion, the trick to writing a successful getting started guide is
for the final product to meet two purposes that are somewhat contradictory.
First, a getting started guide should be something that Marketing can take
to a trade show and make available to passersby as an introduction to the
product. For this purpose, the getting started guide has to pass what one
might call the "thumb through" test. I mean by this that the guide has to
make a positive visual impression on someone who thumbs through it casually.
This means that the guide has to be laid out attractively and that it needs
to include illustrations that have what we might call "curb appeal."
At the same time, the getting started guide has to include substance that
actually helps someone begin using the system. A task analysis will help you
identify the necessary content if you answer the question, "What does a user
have to do and to know to start using the product productively?" The answer
may or may not include technical procedures such as installing and
configuring software. In my experience, a lot of users read the Quick Start
Guide cover-to-cover, though they may not use other documentation except as
an occasional reference.
The challenge is to design and write a document that includes both marketing
fluff and solid technical information. Depending upon the politics of a
particular organization, this may not be easy. In a previous assignment, I
had to work with a Director of Marketing who "edited" my content so that it
would be in passive voice. When I asked why these edits were made by her,
she said that writing that way was seen as more effective by her. Lack of
management support for writing standards let loose a really wretched
document upon the world. Guess who got blamed when prospects trashed it?
As for samples, most software packages contain some sort of Quick Start
Guide. A good place to start might be to review some of these guides to see
how they include both "curb appeal" and technical content.
