Re: Wording too dense? OK?

["heidi arnold" <heidi -dot- w -dot- arnold -at- gmail -dot- com>]

it sounds like your source expects readers of these documents to know UNIX
well.  in that case, if your source doesn't have time to review the
document, it might help to find a reader who knows the UNIX.  if your
concern is for someone who does not know the project to be able to step in,
and find enough information in the documentation to develop the project,
then maybe writing a companion set of documents for that different kind of
audience wd be helpful such as explanations of the content of the project
and vision for its direction, rationales behind structures created, and so
forth.  although it doesn't sound like that particular kind of documentation
wd interest your source.  regarding the verb tense and choice of words such
as adverbs in technical documentation, i think it depends on the context.
without knowing the unix or the project it's difficult to say if the text is
complete or not.

heidi

On 6/27/07, TECHWR-L Administrator <admin -at- techwr-l -dot- com> wrote:
>
>
> 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 heidi -dot- w -dot- arnold -at- gmail -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/heidi.w.arnold%40gmail.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.
>
>


-- 
www.heidiarnold.org
www.peaceraptor.blogspot.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.