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: Arranging Topics For New Manual From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Mon, 8 Feb 1999 13:20:03 -0700
Debbie Warren wrote:
>I spent most of my time rearranging topics in a new manual. I'm thinking
>about creating a file for each topic.
>
>I'll give the reviewers all the topics to arrange in the order that they
>prefer. After receiving their feedback, I can merge the topics together into
>one document. Has anyone used this method for organizing topics in a new
>manual?
I haven't tried this, but I'm afraid my gut reaction isn't too positive.
In engineering, one typically distinguishes between "function space" and
"design space". Function space is the set of possible effects of interest
that you're trying to create. In an airplane, that would include such
things as lift, stability, drag, maximum flight distance without refueling,
etc. Design space is the set of possible designs that you're searching
through in the hope of creating those desirable effects--the things, or
attributes of things, that you hope will produce those effects. In an
airplane, that would include things like wingspan, wing shape, engine type,
size of fuel tank, fuselage width, etc.
I think this same kind of distinction is applicable to many other things,
including user's manuals. When I get feedback from SMEs or users, I try to
focus everything on function space: did they understand A, can they do B,
did they know that they can do C, how long did it take them to find D, was
information E correct, etc. I don't ask them, "Which section do you think
should come first?" or even "Did you like the way the manual was organized?"
Asking non-writers to propose design decisions for you greatly changes the
way they look at the manual. Many stop thinking about the functions of the
manual (the only thing that counts) and start thinking about very bad
design principles that they were taught in elementary school, like "rules"
about split infinitives and sentences that end with a preposition, or
foolish ideas about organization. (For example, some have heard of the 7
+/- 2 rule and apply it simplistically.) Also, when you invite people to
kibitz in this way, usually there's a great deal of variation in their
responses. You certainly don't want to design by vote, so you end up
having to contradict virtually everyone's suggestions, sometimes making
reviewers feel slighted. Or you might end up in the very awkward position
of having to justify your design decisions to your readers.
On the other hand, asking a fellow tech writer to suggest design ideas is
different. A (good) tech writer looks at a manual not as following little
official rules of design (sometimes very misleadingly called
"correctness"), but as producing effects in readers' minds that help them
get jobs done. A tech writer is always searching through design space to
find the alternative that corresponds to the best trade-off in function
space. That is, a good tech writer is thinking about the design and the
effects of the manual in parallel. Most non-writers do not think this way.
They tend to view the design as an end in itself--or rather, conformity to
prescriptive rules as an end in itself.
Of course, if you come across a non-writer who "gets it", then certainly
ask him for suggestions about the organization or any other aspect of a
manual you're working on.
By the way, here's a great web site about function space and design space
and the value of distinguishing them:
