discuss: [jfleck@inkstain.net: GNOME Documentation Style Guide]
Subject:
Re: [jfleck@inkstain.net: GNOME Documentation Style Guide]
From:
David Lawyer ####@####.####
Date:
6 Jul 2001 06:11:06 -0000
Message-Id: <20010705224152.A542@lafn.org>
On Wed, Jul 04, 2001 at 04:54:45PM -0400, Greg Ferguson wrote:
> On Jul 4, 4:59pm, Dan York wrote:
> > Subject: Re: ####@####.#### GNOME Documentation Style Guide]
> > David,
> >
> > > Take a look at this Style Guide put together by the GNOME project. It
> > > is most excellent.
> > >
> > > http://developer.gnome.org/documents/style-guide/
> >
> > I, too, found it very useful.... [...]
>
> (fyi)
>
> I added a link to the guide in the LDP author's resource area...
>
> http://www.linuxdoc.org/authors/#resources
>
> Excellent guide. Well-done.
Well, I looked at some of it and I disagree. There are likely
many other guides to technical writing that are better, but I've never
looked at any of them. However, if one has read the technical
writings of others, this is in itself an experience in learning about
technical writing. Here's my critical comments on a small part of it.
I feel like I'm playing the devil's advocate since I'm only presenting
the contrary view.
> Avoid humor
Humor distracts from the information you are trying to provide,
and makes the document difficult to translate.
A little humor lightens the reading task, unless it's overdone.
People need to laugh sometimes.
> Avoid contractions
Contractions can confuse readers and translators. For example,
"is not" is clearer than "isn't".
Isn't this contraction in most dictionaries? It's commonly used and
perfectly clear to most people.
> Avoid insider language
Insider language includes both undefined jargon and the
tendency of the computer community to shorten words. For
example, use "documentation", not "docs".
"Insider language" helps to promote new words but it can be overdone.
Eventually the "insider Language" may make it into general
dictionaries.
> Avoid personal opinion
Whether you think a function is useful or woeful is irrelevant.
Report the function to the user, with instructions about how to
use the function. Stay technical.
If the opinion is important and useful, it belongs in the doc. If
there is more than one way to do something, it's important to suggest
which way is best (which may depend on the circumstances).
> Avoid topical expressions
A common saying might be popular and widely used today, but
tomorrow the same saying can convey something altogether
different.
If others can modify the doc, then when it loses popularity it can be
removed.
> Avoid sexist language
Do not get tied in knots with his/her or s/he. These pronouns
do not exist. Stay neutral.
I'll agree that his/her is too long but s/he is not too bad.
Traditionally "he" was understood to included "she". So if someone
wants to use all "he's" (or all "she's"), why not?
> Avoid aspirational statements
Statements about the future developments of a product do not
belong in technical documentation. Write about what you see
right now. Stay real.
Future possibilities do belong in a doc. It might even help improve
bad situations by motivating readers to do something about it. Also
it will help keep the doc current if it anticipates future
developments based on insider information (e.g someone is proposing
that x go into the kernel). Of course, you clearly state that such
features are only proposed.
> Avoid culture-specific language
There is little point in giving examples that everyone in
your town knows about, but is a complete mystery to everyone
else. Think universal.
Agreed
> Avoid talking down to your reader
There are few experiences more irritating for a user than
documentation that says an action is easy or quick, when in
fact the user can not complete the action. Do not qualify or
prejudge actions. Stay factual.
It's important to give the reader some idea of the difficulty of
a task. It's not only so that the reader will know about how much
time to allocate to it, but also so that the reader can decide is s/he
wants to undertake it at all.
So based on these and other shortcomings of this style guide, I don't
feel too bad that LDP doesn't use it. But that's only my opinion.
David Lawyer
