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:"Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM> Date:Mon, 8 Feb 1999 13:39:50 -0800
>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.
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
started.
>>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 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 position
>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.
