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

[bchoc at t4tcolorado.org]

I'm fairly new to the list and have been "listening in" for a little
while, so I'm going to ask a question that is perhaps somewhat ignorant
of the way things are done here.  Or maybe even entirely ignorant ...
just wait and see.

I see that Drupal has something of a style-guide
(http://drupal.org/node/22299) which actually addresses this issue in
this inquiry rather clearly:  "Avoid using personal pronouns: I, my, we,
our, etc.".  Is this style guide a living document that is updated and
reevaluated or is it fairly etched in, ah, pixels.  The reason I ask is
because I want to know if this discussion regarding the use of 2nd- vs.
3rd-person is meant to beget change in the style guide or simply
establish wiggle-room for exceptions.

I see that the guide is rather sparse, and doesn't (apparently) answer,
for example, the recently posted/answered question about a standard way
to include images in a documentation page.  In the same vein, what about
expectations regarding ALT tags and any visual standards?  If not in the
style guide, where should this be (or is this) documented, or should it
not be?

I do appreciate this is a community endeavor and the ramifications of
that; I'm just throwing this out there so I can get a better
understanding of how things are done.  Thanks,
Brian


Chris Miller wrote:
> 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
>>   
>>     
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>