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

[O Govinda]

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.  
> 

I respect that those who say no to "you" are relying on standard
authorities. And I can understand why strictly technical scientific writing
would shun the casual use of third person. "When you take an ordinary
hydrogen atom and double its weight, you get a deuterium atom." Too
informal. And besides, who's the "you"?

But for documenting software, three cheers for spoken-type language!

Here's a genuine excerpt from a technical document I have on hand about a
medication:

    "The oral bioavailability of ibandronate is reduced by about 90%
    when Boniva is administered concomitantly with a standard
    breakfast in comparison with bioavailability observed in fasted
    subjects. There is no meaningful reduction in bioavailability
    when ibandronate is taken at least 60 minutes before a meal.
    However, both bioavailability and the effect on bone mineral
    density (BMD) are reduced when food or beverages are taken less
    than 60 minutes following an ibandronate dose."

As technical documentation, fair enough. But what do we tell the patient?
The same story, but this way:

    "If you take Boniva with a meal, your body will absorb only 10%
    as much of the drug. So take Boniva on an empty stomatch and wait
    at least 60 minutes before you eat or drink anything. When you
    take Boniva this way, your body can fully absorb it, and it will
    do the most to strengthen your bones."

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:

-------------------------------
    Turn Direct Memory Access (DMA) on or off

    You must be logged on as an administrator to perform these steps.

    Direct memory access (DMA) is usually turned on by default for
    devices such as hard disks and CD or DVD drives that support DMA.
    However, you might need to turn on DMA manually if the device was
    improperly installed or if a system error occurred.

    Click to open Device Manager. If you are prompted for an
    administrator password or confirmation, type the password or
    provide confirmation. . . . 

--------------------------------

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
-- 
View this message in context: http://www.nabble.com/What%27s-wrong-with-%22you%22--tf4709543.html#a13523362
Sent from the Drupal - Doc mailing list archive at Nabble.com.