Re: Arranging Topics For New Manual

[CASSIN Gilles <GCassin -at- MEGA -dot- COM>]

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.

-----Message d'origine-----
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
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.

HTH!

-Sue Gallagher               http://pw1.netcom.com/~gscale/susanwg/
sgallagher -at- expersoft -dot- com     http://www.expersoft.com

The _Guide_ is definitive.
Reality is frequently inaccurate.  --Douglas Adams

 From ??? -at- ??? Sun Jan 00 00:00:00 0000