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

[Lynette]

I completely agree - I review several thousand pages of software 
documentation every year. I also write a lot of short bits of things 
that are directly user/customer facing, with the purpose of explaining a 
problem, a function, or a specific task they need to accomplish.

Our docs only use the 'you' form, because we the writers, are telling 
you, the readers/users, what to do. First, you do this. Next, you do that.

It's been a great improvement for us. Our users feel it is much much 
clearer and easier to understand what they have to do. If it doesn't say 
'you', it is most definitely implied. I will note though, our 
documentation is extremely task based. That may not always be the case 
in Drupal's documentation.

Besides, the greatest thing about standards... there's so many to choose 
from.

- Lynette


<bits below hacked for brevity>

O Govinda wrote:
> 
> Chris Miller-18 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.  

> 
> Which style fits better for documenting Drupal?
> 
> If this example and the one from IBM aren't close enough, here's another,
> chosen at random from the help texts written--by professionals expert in
> documentation--for Windows Vista:
> 
> And so on. "You. . . you . . . you. . ."
> 
> So while, yes, third person may be the standard for technical writing, to
> tell someone how to do something (like use Windows or Drupal) nothing quite
> beats "you."
> 
> Cordially, 
> O Govinda