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: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.
Thanks
-Matthew Craver,
Documentation Supervisor
Open Solutions Inc.
Mcraver -at- opensolutions -dot- com
