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

[Chris Miller]

http://www.ent.ohiou.edu/~valy/techwrite.html

The convention for technical writing is third person.  In a diverse open 
source community like this, use of "you" allows too much loose, 
spoken-type language slip into technical writing.  In the IBM license 
example, there has to be some label to identify the parties in the 
contract, so I don't consider it a good comparison.  Avoiding passive 
voice is a good thing, but it should be a rule rather than a side-effect 
of the allowed use of "you".  Clear use of antecedents is a separate 
problem as well.

My 2 cents...
  Chris.

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
>