theory behind document usage; sage input please.

Subject: theory behind document usage; sage input please.
From: "Wright, Lynne" <lwright -at- positron911 -dot- com>
To: Techwr-l <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 2 Mar 2004 15:09:33 -0500

I work for a company that develops software used by emergency response
centers to process 9-1-1 calls, dispatch response teams, etc.

Our documents have traditionally been written with the assumption that users
will be learning the product by reading our manuals... ie. they're going to
sit down and start at the first page of chapter one, and read through to the
end. This is in spite of the fact that when a customer buys one of our
products, installation and initial configuration is done by our company
reps, and users are introduced to the software in a course led by one of our
training staff, complete with training handbook.

The problem that arises is that in our user manuals, there tends to be a lot
of duplication of very simple information, as writers try to cover all
possible bases in each section/procedure... we also tend to illustrate every
freakin' move a user has to make in a procedure... even a simple "Click OK."
There are also lots of cross-references like "for more information on how to
create a list, refer to Section 1.2 Creating Lists."

I've recently taken over editorial duties, and would like to convince my
colleagues that this approach is unrealistic. My feeling is that a manual is
a reference book; ie something that people dip into to find information as
required, after learning the basics from a tutorial (either live, online,
whatever). I'd like to work under the assumption that if a user reads a
procedure and it refers to another module, for example, they'll have the
wherewithall to refer to the relevant section on that module if they need
further information.

Compounding the problem is that the product managers have gotten used to
this concept of basically beating the horse to death, so if I, as editor,
ask for the 20th instance of a simple tip to be removed, or the 5th instance
of the same figure taken out, they might well insist that it be left in.

So I seek your collective wisdom as to what your average user guide is meant
to do.

ALSO... we've been using military numbering for our sections (ie. section
1.0, sub-section 1.1, 1.2, etc), even though our products are relatively
simple, and the documents similarly not terribly unwieldy (ie there's no
need to cross reference to very specific bits of information within a 10,000
page manual. The TOC and Index should suffice). Is there any compelling
reason to keep this numbering style? I really don't think it adds anything
to the documentation... it just makes the TOC look more confusing.

thanks in advance

Lynne Wright
Technical Communications
Positron Inc.
5101 Buchan St. H4P 2R9
(514) 345-2200
fax: 345-2272


Previous by Author: Re: "DO NOT COOK"?
Next by Author: Doc comparisons in Framemaker MAKING ME NUTS!!!
Previous by Thread: RE: Microsoft... no flame wars
Next by Thread: Re: theory behind document usage; sage input please.

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

Sponsored Ads