TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Documenting a confusing process From:John Posada <jposada01 -at- YAHOO -dot- COM> Date:Mon, 24 May 1999 08:24:13 -0700
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.
> -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
> Send commands to listserv -at- listserv -dot- okstate -dot- edu
> (e.g., SIGNOFF TECHWR-L)
> Search archives at:
> Find TECHWR-L-related books at
> Send all list-related questions or problems to
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