FWD: Wording too dense? OK?

[TECHWR-L Administrator <admin -at- techwr-l -dot- com>]

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.


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

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.