Re: Document Planning

[Bill Kilpatrick <whk3 -at- PRIMENET -dot- COM>]

Matthew:

I'd write an introduction that describes the "universal" concepts and
procedures, but I'd also include the  information in each flavor's
section--for the following reasons:

*Users may not read the introduction
*Users  may only read one flavor
*Even if they've read the introduction and/or one particular flavor, users
may not recall the common procedures or interface elements when reading
about another flavor.

To accomodate users who must read two or more flavors, you might consider
using typographical elements to identify common stuff. You might also
rephrase the common sections to make them less repetitive--and hence, more
"readable"--and to improve their instructional effectiveness. As you know,
describing the same procedure or screen element in several different ways
improves you chances of making a connection with users--no matter what
their learning style.

Bill Kilpatrick


----------
> From: Matthew J Long <mjl100z -at- MAIL -dot- ODU -dot- EDU>
> To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject: Document Planning
> Date: Tuesday, June 10, 1997 7:43 AM
>
> I'm stumped!
>
> I am the only tech writer at my job and I am a youngster. I have
> relatively little experience (8 months) and I have no guidance. Help me!!
>
> 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.
>
> 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)?
>
> Please include advice and rationale. Thanks!
>
>
>
> ////////////////////////////*****************************
>
>         Matthew J. Long
>         mjl100z -at- mail -dot- odu -dot- edu
>         matt -dot- long -at- justice -dot- usdoj -dot- gov
>
> *************************************************////////////
>
>  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

 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