Re: one word, not "if", for "as long as"
Lauren wrote:
"You"? I prefer to avoid pronoun references in technical documentation.Interesting preference. Some of us would say that preference is an example of what you earlier referred to (in the "Help with a term" thread) as "ancient pedantry. ;-)
My preference is based on my tendency to read as an empathic reader and to write with the reader's feelings in mind.
IMHO, it's good documentation practice to address the reader directly. To Craig's point, avoiding "you" is not only sometimes clumsier but often much less clear.
When I read "you," I feel like the writer is telling me what to, instead of guiding me through the process. I like my documentation (not my email posts) to "sound" like a thought process in the reader's head, rather than "sound" like someone giving orders to the reader.
I always wonder when reading "you" documents, "why is this document yelling at me?" I worked with one particular document that detailed lists of instructions and nearly every paragraph began with "you." I found that very aggravating. But like I said, I "feel" documents when I read them and I do not like having someone tell me what to do in a micro-management sort of way, like "you do this..., then you do that..., and don't forget to take out the garbage..."
Consider these "you-less" alternatives:
-- The user can use different subdomains, but the top level domain must be the same.
That may be a "you-less" example, but it still refers to a person, so the pronoun is implied and a reference to a person is still there, so it is not a pronoun-less example.
-- Different subdomains can be used, but the top level domain must be the same.
That sentence is awkward, but not for lack of a pronoun. In keeping with your structure and "provided that" as chosen by the OP, I would write the sentence, "Use single or multiple domains provided that the top level is the same." That example is directed to the user without
Unfortunately, none of the examples have provided enough context to understand what "the same" means or refers to, so it is difficult to determine the correct context for "different domains." Is this an instruction for an account setting, where one account can use different domains on one top level domain? Is this a categorization instruction? Is this a reference to an instruction and only one top level domain is available? Or is this like a description of internet domains where "one top level domain can have multiple subdomains" or "one main web site domain can have multiple subdomains on that domain"? Then there is also the issue of what "top level domain" refers to. Internet top level domains are the .com, .net, .org, etc. domains. If the instruction refers to any sort of internet or intranet domain, then "top level domain" can only refer to a top level domain.
...I think a lot...
Anyhoo, back to fixing things...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://bit.ly/doc-to-help
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
References:
Re: one word, not "if", for "as long as": From: Laura Lemay
Re: one word, not "if", for "as long as": From: Lauren
RE: one word, not "if", for "as long as": From: Combs, Richard
Previous by Author:
Re: one word, not "if", for "as long as"
Next by Author:
Re: toilets - Re: Interviewing technical writers
Previous by Thread:
RE: one word, not "if", for "as long as"
Next by Thread:
Re: good forum for Word macro / VBA advice?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads