Involving Users in Doc. Design?

Subject: Involving Users in Doc. Design?
From: PHILA -at- Mail -dot- VIPS -dot- com
To: techwr-l -at- lists -dot- raycomm -dot- com
Date: Wed, 15 Dec 1999 11:51:22 -0500

Did any other Whirlers attend JoAnn Hackos' talk at the STC conference:
"Stop Writing Documentation, Start Writing for the Customer: a
Customer-Focused Strategy for Publication Organizations " ? She dealt with a
number of the issues that we're discussing, from a perspective that (IMO)
went straight to the heart of the matter: determining the user's needs
before creating the documentation, and writing specifically to those needs.

From the best of my memory, here was the gist of her

Originally, technical writers explained how systems worked. Typically, the
audience was composed of specialists interested in becoming experts by
learning the inner workings of a system. Technical writers were likely to be
engineers and programmers who were only too happy to provide that
information, whether clearly or otherwise. Encyclopedic reference manuals
were the result.

When task-oriented information - how to do XYZ - was introduced in 1983-84,
it was big news. The idea was to get the technical writers closer to the
developers, more involved in the development cycle, in order to be advocates
for the users. Task-oriented documentation was designed to present the
system from the user's point of view: not "what is this?" but "what can I
do with this?"

It was a bad move. Because of this close link, writers are so enmeshed in
their products that they tend to think like programmers: focusing on how the
product works, rather than how it can serve the user's needs. Users in most
cases do not need the product specifications, except possibly at a system
administrator's level. But writers often give the users spec-like
documentation of tasks and pseudo-tasks - that is, tasks that exist only
because the related functions exist, not because there is any real need for
them. The users' needs and the writers' documentation are incongruent at a
fundamental level.

So what is the alternative? Designing documentation in close contact with
the people who will use it. Actually asking the users what they need from
the documentation. Writers should go out to client sites and observe and
analyze the customers' workflow, then structure the documentation based on
the customers' specific questions, work patterns and business needs. The
primary question should not be "How does this work?" to the developers, but
"Tell me what you do, what your problems are," to the customer.

We're experimenting with this approach in our new document design process;
given the nature of our product and our documentation, it seems to be an
ideal match. I'd like to hear whether other writers have tried this, and if
so, what were the results?

Philomena Hoopes
Phila -at- vips -dot- com <Phila -at- vips -dot- com>
(410) 832-8330 ext. 845

Previous by Author: Acrobat Help
Next by Author: RE: Baseline Skillset for Technical Writers?
Previous by Thread: More or less - Was Tracking Off
Next by Thread: RE: Involving Users in Doc. Design?

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

Sponsored Ads

Sponsored Ads