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:CASSIN Gilles <GCassin -at- MEGA -dot- COM> Date:Tue, 9 Feb 1999 09:50:01 +0100
I strongly disagree with the fact that making an outline before starting
to write should be the rule. As a matter of fact, deciding a list of
topics and the organization they should have before having any written
material has two major drawbacks: you try to cram material you didn't
foresee where it can fit, and you tend to pad out subjects that would
only take a few lines.
Moreover, when a document evolves, its initial outline often has to be
revised. Of course, if the matter is self-organizing (for instance,
functions to be described), this is not true. But when you come to user
guides, I think overplanning often give poor results.
De: Susan W. Gallagher [mailto:sgallagher -at- EXPERSOFT -dot- COM]
Date: lundi 8 février 1999 22:40
À: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Objet: Re: Arranging Topics For New Manual
>Debbie Warren wrote:
>>I spent most of my time rearranging topics in a new manual. I'm
>>about creating a file for each topic.
This says to me that you're process lacks a strong planning phase.
After all, you wouldn't create a bunch of random highways, then
connect them all together to see where they take you! Of course
not, you'd want a strong sense of direction before you bring in
the earth-moving equipment.
Likewise, when you plan a document, you want a strong sense of
direction, in the form of a good outline, before you ever get
>>I'll give the reviewers all the topics to arrange in the order that
>>prefer. After receiving their feedback, I can merge the topics
>>one document. Has anyone used this method for organizing topics in a
I agree with Ben Kovitz when he said:
>... 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
>of having to justify your design decisions to your readers.
If you really feel like you need help from your users, ask them what
kinds of tasks they expect to be able to perform with the software and
the order in which they expect to do those tasks. That will help you
get a handle on what you need to cover and where, in the overall scheme
of things, the topics should go. *Don't* let them think they have input
into the structure of the book. Ideally, do the asking before you write
a single word.
While you might want to spend a lot of time in the beginning looking at
different structures, once you settle on an outline and begin to write,
there should be few, if any, changes. -- And by few, I mean once in
every 3 or 4 books you might decide while writing that a topic fits
better here than there.
I'm always surprised when professional writers skip the outline phase
and jump right to the writing. Imposing the discipline of a structured
outline helps ease the task of writing considerably. Once the outline
is in place, writing becomes a matter of filling in the details --
much easier than structuring as you go.
A good, solid outline can also help you filter information that the
programmers give you -- if it doesn't fit easily into the structure
of your book, perhaps it's information that the user's don't need.
(Notice, I said *perhaps*!)
MS Word, for all it's apparent and percieved faults, has an excellent
outlining feature. You can quickly promote and demote headings and
move topics from one section to another, and when you move a collapsed
heading, all its subsections move with it.