Re: personal pronouns

[Shaun McCance <shaunm gnome org>]

On Fri, 2010-08-06 at 17:25 +0930, Craig Keogh wrote:
> I do not like personal pronouns (you, your, he, she) in documentation.
> The GNOME style guidelines [1] doesn't say much about personal pronouns,
> but 'Topic 2 Passive Voice' [1] suggests it. Active voice is good. Using
> 'you' is not.
> 
> Fedora's guidelines [2] state avoid personal pronouns. To steal Fedora's
> example:
> 
> BAD:
> "Edit your yum configuration files to use geographically close mirrors."
> 
> GOOD:
> "Edit the yum configuration files"
> 
> I've been seeing a lot of personal pronouns in the new Mallard
> documentation. Thoughts?

I write help as I would talk to users. I don't talk about
what "I", "we", "he", "she", or "they" do, but I will say
what "you" do. It's casual and informal, and a lot more
engaging.

Instructions are written in the second person whether you
use "you" or not. Avoiding "you" is stereo-instruction-esque.

And as long as I'm beating down traditional style guidelines:
Contractions are OK. Ending a sentence with a preposition is
OK. The word "OK" is OK.

It doesn't have to be dry just because it's instructional.
Writing should be fun.

--
Shaun