Re: Documenting a confusing process

Subject: Re: Documenting a confusing process
From: John Posada <jposada01 -at- YAHOO -dot- COM>
Date: Mon, 24 May 1999 08:24:13 -0700

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
> Search archives at:
> Find TECHWR-L-related books at
> 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

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

Previous by Author: Re: Phrasing Question
Next by Author: Re: Using articles
Previous by Thread: Documenting a confusing process
Next by Thread: Re: Documenting a confusing process

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads