Documenting a confusing process

Subject: Documenting a confusing process
From: Matt Craver <MCraver -at- OPENSOLUTIONS -dot- COM>
Date: Mon, 24 May 1999 11:11:56 -0400

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=

Previous by Author: Re: Environment statement after copyright
Next by Author: **READ THIS** (Re: ADMIN: Posting Rules Reminder)
Previous by Thread: Re: Writing vs. Testing, one last thought.
Next by Thread: Re: Documenting a confusing process

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

Sponsored Ads