[documentation] What's wrong with "you"?

[Bill Fitzgerald]

A recovering English teacher speaking here, so take this for what it's 
worth :)

Directly addressing your audience using the second person (you) was 
generally considered to be a sound rhetorical device, but something 
unfit for formal writing. This convention holds today for literary 
analysis, and most academic writing. In technical writing, however, the 
direct address of the second person can be effective.

Some links:

http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Avoid_second-person_pronouns
http://www.writersblock.ca/tips/monthtip/tipsep97.htm
http://owl.english.purdue.edu/owl/resource/683/01/ -- probably the best 
of the lot for describing the conventions of academic writing

Cheers,

Bill

Lynette wrote:
> Nothing wrong with you.. or 'you' for that matter.
>
> I had this discussion a few years ago with one of the technical writers 
> I was working with. I thought 'you' should be eliminated, based on some 
> previous experience. However, when I went to look for backup, I really 
> couldn't find anything. It's a style. Now that I've gotten used to it, I 
> actually like it a great deal, for all of the reasons you outline. It's 
> an imperative. I think it is significantly more useful when writing 
> instructions than any other method I've ever had to use (as a 
> writer/reviewer or target of docs.)
>
> - Lynette
>
>
>
> O Govinda wrote:
>   
>> I've lately seen a few comments that speak favorably about ridding Drupal
>> documentation of the word "you."
>>
>> I don't understand the reason for doing so. Perhaps there's some
>> conversation I've missed. 
>>
>> >From my point of view, "you" is one of the most exceedingly useful words for
>> documentation in the entire English language. 
>>
>>    * It's simple, plain, and direct. 
>>
>>    * It's short--only one three-letter syllable. 
>>
>>    * It's gender neutral. 
>>
>>    * It's superbly personal and friendly.
>>
>>    * Unlike "they," it never invites doubts about antecedents. ("When users
>> modify these settings, they. . . " The users or the settings?)
>>
>>    * It leads you naturally to write about what the *user* has to do rather
>> than what a module does--and that's very good indeed for the user. 
>>
>>    * It leads you naturally to write in the active voice, rather than the
>> passive, thereby avoiding one of the greatest killers of clarity known to
>> the English tongue.
>>
>> Even legal contracts these days tend to replace the old clunky impersonal
>> terms with the equally legal, and far more clear and friendly, "you." For
>> example, from an IBM license:
>>
>>    ------------------------
>>
>> As used in this End User License Agreement, "you" and "your" refers to the
>> individual or entity that wishes to use the Software.
>>
>> 1. License.  Subject to the terms of this Agreement, you are hereby granted.
>> . .  
>>
>>    -------------------------
>>
>> I'd say that rather than trying to curb "you" for Drupal documentation, we
>> should *promote* it.
>>
>> In short: I see nothing wrong with "you." I'm all for it. Or is there
>> something wrong with *me*?
>>
>> Cordially, 
>> O Govinda
>> www.jswami.info
>>     
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
>   


-- 
Bill Fitzgerald
http://www.funnymonkey.com
Tools for Teachers
503.897.7160