Re: Document Planning

[Tim Altom <taltom -at- IQUEST -dot- NET>]

At 10:43 AM 6/10/97 -0400, you wrote:

>I am in the document planning stages again for a document that I have
>already rewritten twice to meet new "requirements" from our client. The
>upside is the fact that I can do it however I deem appropriate. The
>downside is that I am not sure of myself. I have my own *opinion* on
>style, but I just don't *KNOW* what is best.

You'll never KNOW what's best. Ours is not a profession of certainty. That
has its charms, though.
>
>We have developed a GUI interface which allows users to access a database
>easily. The problem is that this interface has four different flavors.
>They want the End User Guide (which I am writing) to include a section for
>all four flavors. The application looks relatively similar in each flavor
>but there are components in each that are distinctive enought to warrant
>giving them their own sections.
>
>What I am wondering is whether or not I should repeat information that is
>the same for each flavor in every section, or should I write it once and
>make reference to it in the other sections. And if I do write it once, in
>which section should I write it (i.e., the most complicated flavor or the
>least complicated)?
>

There are two competing factors at work here, as in all such projects: user
needs and producer needs. The user may benefit from having information
endlessly repeated, but the maintenance problems will likely cost dearly
over the life of this material. If the document can be put online as
hypertext, the problem is solved. However, in print, you'll need to compromise.

We often compromise this way: most _explanations_ are only needed once and
referenced elsewhere. Thus "why we're doing this" is given its own section
that's referenced from each task. Tasks, the "how", are modified to suit and
placed in each area. We much prefer task-based documentation wherever
possible anyway. It's cleaner, faster, simpler to produce and use, and it
lends itself to these balanced compromises.

 It looks a little like the silly sample below.

<first section>
Opening The Gelunkenskeit Number One

1. XXXXXX
2. XXXXXX
3. XXXXXX

For more information about Gelunkenskeits, see page 345.

<second section>
Opening The Gelunkenskeit Number Two

1. XXXXXX
2. XXYYXX
3. XAABBXX

For more information about Gelunkenskeits, see page 345.

Same reference, different steps. Users should be served and updating is made
much, much easier. Even explanations about "flavors" can be quickly adapted
to this, especially if you can write general explanations, then write
successive paragraphs about each flavor and let the user pick out the one he
or she wants. But we make strong distinctions between "how" and "why".
Experience and research has shown that users don't turn to documents for
long-winded explanations very often. They want help and they want it now.
Step tasks serve that purpose best.




Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support  ForeHelp support
FrameMaker-to-HTML Conversions
HTML Help Consulting and Production

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html