Re: Documenting a confusing process

[Michele Marques <mmarques -at- CMS400 -dot- COM>]

Matt,

Your scenario seems fairly straightforward to me, although I can
see how confusions could arise in an explanation.

Here's a simple version of what I would say to a non-technical
audience (followed by general suggestions):


You should defragment your Oracle database periodically. If you
wait too long, and the database becomes very fragmented, you will
find the system increasingly slow in responding to your queries.

The most efficient way to defragment your database is to create a
script that does the work for you, and to run this script periodically.

Your defragmentation script will contain information specific to your
Oracle setup, so we could not give you that script directly. Instead,
we provide you with a script-creation script. All you have to do is
run the script-creation script once to create your defragmentation
script, and then you can run your defragmentation script
periodically to defragment your Oracle database.


------

Here are some general principles I followed that you could apply to
other similar situations.

First, you have a possibility of confusing the user through referring
to two different scripts; the user must be clear to which script you
are referring.  I resolved this problem by naming them "your
defragmentation script" and "the script-creation script".

Second, it may be difficult for some people to understand why they
need to run a script to create another script. In addition to
explaining the reason, I always referred to the "defragmentation
script" as "YOUR defragmentation script" and the provided script
as "THE (script-creation) script". This was to emphasize that the
resulting script is personalized for the reader.

Finally, I used a trick that even works outside the non-technical
writing sphere to persuade the user... I figured that if you start by
saying "we have this script to run, then you run the script it creates
in order to defrag....", the users (as you anticipated) will be
annoyed that you couldn't just give them the defrag script they
need... or may even want to just skip the whole defrag business.
So, I state problem, followed by solution (here's what happens if
you don't defrag.... you can solve this by running a script; here's
why we can't just give you the script... but aren't we nice to give
you a script to create that script).

I hope this helps.

       - Michele

----------------------------------------------
Michele Marques
Technical Writer, CMS Manufacturing Systems
mmarques -at- cms400 -dot- com
905-477-4499 x280

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