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 _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
