FWD: Wording too dense? OK?

Subject: FWD: Wording too dense? OK?
From: TECHWR-L Administrator <admin -at- techwr-l -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 27 Jun 2007 06:28:49 -0600

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

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

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


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.

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.


Previous by Author: FWD: Employment question
Next by Author: TECHWR-L Premium Jobs, Events, and Announcements
Previous by Thread: RE: "face time" at the office
Next by Thread: RE : FWD: Wording too dense? OK?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads