RE: Wording too dense? OK?

["Lauren" <lt34 -at- csus -dot- edu>]

Hey Anon,

I used to work with Unix.  I engineered web systems and wrote apps and
stuff.  Plus, I documented what I did.  You really don't need to say a lot,
but some things in your example are stated a little badly.

> 4. Create db_env_{SID}.bat:
> 
>     a. DB and ORACLE_SID set to {SID} needs to be created.
> 
>     b. ORADIR oracle_home.

"a" should probably be re-worked, but you will need to talk to the developer
because I haven't worked with Oracle.  Is is it, "set DB and ORACLE_SID to
{SID}" or is it "Create {SID} and set DB and ORACLE_SID to {SID}"?

Change b to:

"Set ORADIR to oracle_home."

If you have font options, then "ORADIR" and "oracle_home" should be in the
appropriate fonts.  Presumably bold for "ORADIR" and italics for
"oracle_home." 

> 
>     c. SCRDIR script directory.

Change to:

"Set SCRDIR to the script directory."

"The script directory" may need more explanation, like "current script
directory" or "script directory for the current system" or "script directory
for the new database."  Some convention should be adopted for how to refer
to the new _things_ being built.

This sounds like it is the directory that the administrator has determined
for the particular system.

>     d. Point the FILDIR directory where you want the database 
> files to 
> be created.
> 
>        Note that it will append the database files to it so the path 
> will be FILDIR\DB\.

Okay, this is just badly written.

Change to:
"Point FILDIR to the new database files directory."

"New database files directory" requires the same type of discussion as
"script directory."  Some form of consistent reference to the _thing_ needs
to be established.  Is this a "new" database?  An "xyz system" database?  Or
what?  Find a way to consistently refer to the thing being built and refer
to the thing the same (or similar enough) way each time.

Change to:
"Note:  The FILDIR pointer will append new database files to this path so
that the database file path will be FILDIR\DB\."

You might want to trim the above note, but that explains what is happening.
"DB" should be offset with the font you use for variables, unless the
developer intends that "DB" is the directory name.

> 5. Create init{SID}.ora:
> 
>     a. In the Diagnostics and Statistics section, change the 
> location of 
> the diagnostic files accordingly.
> 
>     b. In the File Configuration section, set the location of the 
> control files accordingly.
> 
>     c. In the Miscellaneous section, change the compatible 
> and db_name 
> parameters accordingly.

Argh.  I hate sentences written this way.  Here's how I would address this.

5. Create init{SID}.ora and make the appropriate changes in the sections
that follow.

    a. Diagnostics and Statistics
	 - Change the location of the diagnostic files.

    b. Configuration
	 - Set the location of the control files.

    c. Miscellaneous
	 - Change the compatible and db_name parameters.

"Appropriate" should probably be more informative, but will likely follow
whatever convention is adopted for "script directory" and "new database
files directory."

Lauren

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.