GNOME Documentation Style Guide

[Paul W. Frields]

On Mon, 2004-08-23 at 07:36, Karsten Wade wrote:
[...snip...]
> This came about because of a heated discussion about sexist language.  I
> heard about this from someone saying, "Look at these idiots on this
> mailing list arguing such dumb stuff!"
> 
> http://lists.debian.org/debian-doc/2004/08/msg00006.html (start 1)
> 
> http://lists.debian.org/debian-doc/2004/08/msg00015.html (next
> continuation)
> 
> I think the GDSG guideline stands, and it is the one I have always
> used.  Avoid sexist language, mainly by avoiding the third-person
> pronoun.  We should specify that all of our docs refer to the
> second-person pronoun 'you.'

I agree whole-heartedly. If documentation avoids referring to users by
pronouns at all, it shifts to passive voice, and there's nothing that
irritates me more. Well OK, that and people who take the last bit of
coffee without making another pot.

My workplace practically insists on passive voice, and I fight it at
every opportunity. My last job here was as a forensic examiner, and all
my work products could potentially wind up in court at some point. For
some reason, it was de rigeur to write all the lab reports in passive
voice, such as "this test was performed." I started writing my reports
as "I ran this test," and it caused a bit of an uproar. My position was
that if I had to sit on the stand and say I did something, why should my
reports not say the same thing?

There is the indefinite subject "one," but that's too dry and effete for
my taste. I also prefer "you," since it gives readers the sense that the
documentation is at least *attempting* to address their personal needs.
It also reduces unnecessary formality, without making the documentation
seem inauthoritative.

I've only skimmed the GDSG so far, but will read it in its entirety this
week and start making notes on what I think we should cleave to or
depart from. (Paying attention to dangling prepositions, of course. And
sentence fragments.)

-- 
Paul W. Frields, RHCE