discuss: Thread: [jfleck@inkstain.net: GNOME Documentation Style Guide]

Take a look at this Style Guide put together by the GNOME project. It
is most excellent.

http://developer.gnome.org/documents/style-guide/


-- 
Dr. David C. Merrill                     http://www.lupercalia.net
Linux Documentation Project                   ####@####.####
Collection Editor & Coordinator            http://www.linuxdoc.org

What this country needs is a good five cent microcomputer.

Folks -

I'm happy to submit for your consideration the first draft of the
GNOME Documentation Style Guide:

http://developer.gnome.org/projects/gdp/styleguide.html

Our hope is that this will serve as a guide to improving the quality
of our documentation.

It includes sections on:

* Documentation fundamentals
* Usability
* Writing for translation
* Improving your writing

It also has detailed sections on DocBook markup and a word list, that
we might settle on consistent terminology.

A delicate balance is required here. On the one hand, the nature of a
free software project is such that we are uncomfortable imposing
rules. On the other hand, GNOME users will benefit if we are able to
settle on a set of styles and conventions that create consistency and
quality in our documentation. To that end, we need your input, so we
can come up with a final product that reflects the needs of the GNOME
community, something we all can live with and use.

I must thank the people who contributed: Alexander Kirillov for the
DocBook section, Eugene O'Connor of Sun who spent a lot of time and
energy assembling the word list, and especially Pat Costello of Sun,
who wrote extensive sections of this document. While I have been
shepherding its creation, Pat, who has a great deal of expertise in
the subject matter, has done the largest share of writing and deserves
a great thanks.

Cheers,
-- 
John Fleck
####@####.#### (h), http://www.inkstain.net/fleck/

_______________________________________________
gnome-doc-list mailing list
####@####.####
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

I see a lot of good stuff in here. In particular, I love the guidelines
for language style such as keeping sentences short and concise. 

I would love it if we adopted this or a similar style guide. I just
switched companies to be the Tech Pubs manager at Plexus Software and am
currently setting up the style guide. Up to now, they didn't have one
and it's very difficult to work with vague styles that aren't written
down.

However, there are two problems that I see in implementing this or a
similar guide for LDP.

1. Developers, engineers, etc. are the primary writers of the
documentation. Many do not agree with the notion that a common style of
language and format is necessary. Some feel it's nice, but too much
work; some feel it's a waste of time. Most importantly, they do not want
to be hampered in writing the documentation. Writing the documentation
is a favor to the Linux community and adding conditions to that may make
some of these valuable writers not want to bother.

A possible solution to this is to tell writers not to worry about it,
just go ahead and write and reviewers will take care of any style
concerns. This could lead to the second problem.

2. As a reviewer, my understanding of the review assignment is to keep
the author's tone and style intact, making changes only when clarity
and/or grammer need it. Authors may object to having their work
rewritten to conform to a style guide. I've been a tech writer for ten
years and frequently work with engineers who write 50-word sentences
loaded with jargon and narry a comma in sight.

Assuming I'm correct that these are problems, we need to mitigate them
before implementing a specific style guide such as this one. I'm
concerned that we not alienate the people who take the time to write the
LDP docs.

Ami


David Merrill wrote:
> 
> Take a look at this Style Guide put together by the GNOME project. It
> is most excellent.
> 
> http://developer.gnome.org/documents/style-guide/

David Merrill escribió:
> 
> Take a look at this Style Guide put together by the GNOME project. It
> is most excellent.
> 
> http://developer.gnome.org/documents/style-guide/


Maybe is the time for creating a free soft doc style guide.


-- 
	A.Ismael Olea González

	####@####.####
	http://www.hispalinux.es/~olea
	####@####.####
	
	Que les FOLLEN a los de ETA

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.... in fact... I thought I had sent a note to
this list about it the other day.  But... it appears I didn't... I must be
losing what very little is left of my sanity!

Oh... duh... I didn't send it to this list, I tossed the URL onto #linuxdoc
when markk and gleblanc were on there. So maybe I'm not losing my mind.
(Or maybe there's nothing left to lose!)

Anyway, I agree with you about the usefulness of it.  I found the section
on writing for translation quite interesting.

Dan

-- 
Dan York, Director of Training        ####@####.####
Ph: +1-613-751-4401  Mobile: +1-613-263-4312 Fax: +1-613-564-7739 
e-smith, inc. 150 Metcalfe St., Suite 1500, Ottawa,ON K2P 1P1 Canada
http://www.e-smith.com/            open source, open mind

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.

--
Ferg

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

Crap, I am going to agree with David on some points. I hate it when that
happens ;)

>>  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.


>
>>  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.

>>  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 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.

>>  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...

>
>> 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.

>>  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.


>
>>  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.



>
>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
>
>_________________________
>http://list.linuxdoc.org/
>

-- 
--
<COMPANY>CommandPrompt	- http://www.commandprompt.com	</COMPANY>
<PROJECT>OpenDocs, LLC.	- http://www.opendocs.org	</PROJECT>
<PROJECT>LinuxPorts 	- http://www.linuxports.com     </PROJECT>
<WEBMASTER>LDP		- http://www.linuxdoc.org	</WEBMASTER>
--
Instead of asking why a piece of software is using "1970s technology,"
start asking why software is ignoring 30 years of accumulated wisdom.
--

I am not as experienced a technical writer as some of you folks, but my thoughts are a follows:

First, and this is key, I believe that we need to remember our target audience and our purpose.  It is my belief that we are here trying not only to document the information, but to teach it as well.  We write not only for the geek who is looking for answers, but the newbie who is looking for the questions as well.  Everything else is subordinate to these goals.

I've marked the beginning of my comments with ** to make it a little easier to find them.

>>> Poet/Joshua Drake ####@####.#### 07/06/01 02:40AM >>>

Crap, I am going to agree with David on some points. I hate it when that
happens ;)

>>  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.

**My opinion is that the use of subtle humor is appropriate.  All technical writing should be geared towards passing along the information in a way the audience understands.  If humor allows the information to be absorbed easier, than it is appropriate.

>
>>  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.

**There are certain cases where a contraction may be the cleanest way to express an idea.  we should avoid absolutes.  A better phrasing may be "avoid unnecessary contractions".

>>  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.

**I have no problem with insider language if it is defined on first use.  Again, it goes back to our twin goals - documentation and teaching.  Is there a better way for a newbie to learn techie terms than in a document detailing their proper usage?

On a side note, perhaps we need to consider linking to or developing a dictionary of common terms.  this would give writers a consolidated place to reference and ensure that we all use the terminology in a similar manner.

>
>>  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.

**If an opinion is expressed as such, it is relevant.
  
>>  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...

**Remember your audience.  This sort of language may be the best way to convey the thought.
>
>> 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...

**As a female, as long as it is noted in the beginning of the document that "he/his" refers to everyone, I consider it acceptable.  Just mention it once, and your in the clear with most of us :)
>
>>  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.

>>  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.


>
>>  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.

**This is hard.  When writing a universal document, you will have an audience that encompasses people of all skill levels.  I think it has more to do with tone than anything.  

>
>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
>
>_________________________
>http://list.linuxdoc.org/ 
>

-- 
--
<COMPANY>CommandPrompt	- http://www.commandprompt.com	</COMPANY>
<PROJECT>OpenDocs, LLC.	- http://www.opendocs.org	</PROJECT>
<PROJECT>LinuxPorts 	- http://www.linuxports.com     </PROJECT>
<WEBMASTER>LDP		- http://www.linuxdoc.org	</WEBMASTER>
--
Instead of asking why a piece of software is using "1970s technology,"
start asking why software is ignoring 30 years of accumulated wisdom.
--


_________________________
http://list.linuxdoc.org/ 

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"

On Fri, Jul 06, 2001 at 08:49:16AM -0400, Alicia Rojas wrote:
> As a female, as long as it is noted in the beginning of the document
> that "he/his" refers to everyone, I consider it acceptable.  Just
> mention it once, and your in the clear with most of us :)

I think that it doesn't even need to be mentioned.  There are two weak
arguments for using he/his.  One is that "he" is shorter than "she".
The second is that many more users of Linux are men than women.  This
may change in the future.  So since these two arguments are weak, if
someone uses all she/her, that should be OK too.  Or you can use both
he/him and she/her in the same document as Tanenbaum does in his books
on computers.  I just did a grep on my HOWTOs and found that I used
"s/he" a few times, while I used "he" only when I was referring to
certain male authors.  Mostly I used "they" and "you".

			David Lawyer