FWD: Wording too dense? OK?

[TECHWR-L Administrator]

Forwarded anonymously on request. Please respond on list--
no responses will be privately forwarded. TECHWR-L Admin
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&

I need help with the following passage. My source has a bit of the 
mentality "the passage is fine because anyone who's reading the manual 
will know everything already, because I wrote it and *I* know everything 
already and so will anyone reading my text." My source does not welcome 
questions and clarifications that I believe are necessary. I need your 
perspectives.

Here's a brief sample:

****

4. Create db_env_{SID}.bat:

    a. DB and ORACLE_SID set to {SID} needs to be created.

    b. ORADIR oracle_home.

    c. SCRDIR script directory.

    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\.

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.

****
I believe this isn't good enough, even if the reader dreams in UNIX. For 
example:

4a is oddly phrased. I will change to the imperative voice. I think I 
can get acceptance of this much change.

4b and 4c may be intelligible to an UNIX programmer -- but would you 
accept this as is?  One of my standards of technical communication is 
that the text should provide the information needed at each moment, 
clearly and concisely. Maybe that's what this is. Not being a UNIX 
programmer, I can't be sure. What if the reader is a new employee, or is 
temporarily taking over an absent colleague's tasks and in either case 
does *not* dream in UNIX. How much English would you argue for? 
Remember, I can't get a truly helpful response from my source about the 
audience for this book. He stonewalls everything; I'm working at a tiny 
startup and there is no one else to go to other than the CEO, who is 
actually pretty much on the ball regarding tech communication. I may 
need to escalate this. Would you?

4d -- Does this mean "point the directory to another directory"? Does 
the second directory have to be created, or was it created already, or 
will the reader magically know what this means? Do you?

4 "Note that" -- I believe this refers to the directory, but I'd like to 
be sure.

And in step 5, all the "accordingly"s have no antecedents. I'm sure my 
source will tell me that his readers already know what they are. Will 
they? Do UNIX programmers have knowledge of relationships in their 
programs such that they always know what "accordingly" means? That may 
sound like a sarcastic question, but I'm serious -- my ignorance about 
UNIX could be showing.

I truly don't want to make the mistake of overexplaining things that the 
reader does know, that I don't know because I'm not a programmer. 
Neither do I want to let unduly terse language go by simply because I'm 
encountering resistance from my source.

I may have to, though.


I need a pep talk and your sense of how you'd approach this. Thanks very 
much.