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: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
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?