Subject:
Re: [jfleck@inkstain.net: GNOME Documentation Style Guide]
From:
David Merrill ####@####.####
Date:
6 Jul 2001 22:07:04 -0000
Message-Id: <20010706180652.C31719@lupercalia.net>
On Thu, Jul 05, 2001 at 11:40:21PM -0700, Poet/Joshua Drake wrote:
>
> Crap, I am going to agree with David on some points. I hate it when that
> happens ;)
I agree on a few points, but disagree on others.
> >> 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.
>
> Subtle humor is good.
Yes.
> >> 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.
>
>
> We should avoid contractions. Every single editor that I write for (CMP,
> WebTechniques, Linux Journal, Linux World, IBM Develop Works etc..) always
> gets on me about using contractions and makes me change them.
Yes.
> >> 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.
>
>
> I think this would depend on the document. For example, I do things like
> this. Using the File Transfer Protocol (FTP) I can ...
>
> But I don't use things like docs, I will spell it out.
Avoid unnecessary jargon and insider language. Use it where it's the
best possible term, but define it, imho.
> >> 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).
>
>
> Opinion can be very useful, IF you can backup your argument. Otherwise it
> is not a good thing.
Absolutely. I definitely disagree with this point (disagree with the
Gnome guide, that is).
> >> 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.
>
> This depends on what you are writing the document for. If it is a
> commercial pub, I would agree but for HOWTOs? Nah...
It's good advice to try to stay broad enough your doc won't need
updating for awhile.
> >> 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?
>
> This is more politically correct than anything. I still get in trouble for
> using "man" as a general term. E.g. Salesman is supposed to be
> SalesPerson. Personally, I vote for it. SalesIT...
;-)
> >> 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.
>
> I almost agree. You should avoid vaporware statements, but if there is a
> development plan in place, that is publically available, go for it.
Yes.
> >> 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
>
> Agreed but very difficult.
Yes.
> >> 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.
>
>
> This is the absolute most important. This linux shit is hard for most
> people. Don't make them feel stupid.
Absolutely!
> >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.
There is a lot more in the Gnome guide besides these points. I think
these points are the most controversial in the entire document. I do
not want for us to just adopt their guide wholesale. But we should use
what we find useful!
--
Dr. David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Collection Editor & Coordinator http://www.linuxdoc.org
The master programmer moves from program to program without fear. No
change in management can harm him. He will not be fired, even if the project
is canceled. Why is this? He is filled with the Tao.
-- Geoffrey James, "The Tao of Programming"
