Re: Documenting a confusing process

[John Posada <jposada01 -at- YAHOO -dot- COM>]

Hi, Matt...

I don't know if this will work for you, but I'm also
documenting an application, which is also very
complex...multiple layers deep.

In the Introduction section of the manual, since this
manual is country-oriented, I've created a fictitous
country and for that country, defined a scenario with
several business cases.

In each business case, whenever that case uses an
entry that will change based on the user's situation,
I display the entry in italics with a square bracket
around it.  This tells the reader that for a situation
similar to this, use this process, but substitute
their value for the value shown.

Like I said, I don't know if this will work in your
case, but it did for my users.

--- Matt Craver <MCraver -at- OPENSOLUTIONS -dot- COM> wrote:
> Hi all.
> I'm working on documenting a process for
> reorganizing information in an
> Oracle database to eliminate fragmentation.  To help
> our customers, we have
> developed a set of scripts that the customers run.
> Each script generates
> another one that the customers run.  This second one
> does the actual work,
> but we can't create that and send it out, because we
> can't pre-ordain
> Oracle's storage parameters.
>
> As you can probably tell, this is a bit confusing.
> And the audience is not,
> for the most part, Oracle experts.  I'm having
> trouble explaining this
> without dropping in a comment like "Yes, we know
> this is confusing, but
> please  bear with us."  I have tried to eliminate
> this kind of "_For
> Dummies_ voice" from our documents (it just doesn't
> work with our audience).
>
>
> How do other folks create instructions that
> faithfully follow the process
> and illuminate it?  In actual fact, _doing_ these
> steps is easier than it
> sounds.  I don't want to obscure that.
> Thanks
> -Matthew Craver,
> Documentation Supervisor
> Open Solutions Inc.
> Mcraver -at- opensolutions -dot- com
>
>
 From ??? -at- ??? Sun Jan 00 00:00:00 0000=
>        Please search the TECHWR-L archives before
> posting!
> Send commands to listserv -at- listserv -dot- okstate -dot- edu
> (e.g., SIGNOFF TECHWR-L)
> Search archives at:
> http://www.raycomm.com/techwhirl/archives.htm
> Find TECHWR-L-related books at
> http://www.raycomm.com/techwhirl/books.htm
> Send all list-related questions or problems to
>
>
>
>

===
John Posada
Western Union International
(w) jposada -at- westernunion -dot- com
(p) john -at- tdandw -dot- com
_____________________________________________________________
Do You Yahoo!?
Free instant messaging and more at http://messenger.yahoo.com

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