discuss: Thread: Style Guide


[<<] [<] Page 1 of 1 [>] [>>]
Subject: Style Guide
From: "Joy E Yokley" ####@####.####
Date: 5 Jul 2001 16:20:46 -0000
Message-Id: <OF75563713.3B3F0CBC-ON85256A80.00592404@raleigh.ibm.com>

After looking through the GNOME style guide and reading the responses
posted to this list, I thought I would raise some concerns that I have.
First off, I think that Ami made some excellent observations about the
style guide and some of the implementation difficulties we would have
adopting this in its entirity.

As a technical writer, style guides are safe documents for me. They are
guides that  support decisions that we writers make; they validate and
inform writing and style choices.  Style guides lead to more consistent
editing, reviewing, and output across the board.

Now, what concerns me about adopting this style guide for the LDP is that
it seems to be written for technical writers who may already know the
rules. I doubt that someone writing a HOWTO about a fix they just
discovered is going to take the time to read the style guide. Like Ami, I'm
worried that implementing the style guide might discourage publication from
writers.

Because our documents are not written by the developers of the product and
are, largely, based on an individual's personal experience with and fix for
a problem, I don't think that we have to eradicate the author from the
document. The GNOME style guide is based on good corporate technical
writing fundamentals that are "neutral" in tone because they are not the
experiences of the individual. They are the publications of the
corporation. Most LDP HOWTOs are more conversational because they are X
Linux user trying to help out K Linux user. If they contain statements such
as "I tried  q command as recommended, but it didn't work for me because I
am using r distribution," then that is valid information. In my opinion, to
eradicate this typeof information would be a mistake.

A possible plan of action:

* Develop a pared down version of the style guide that focuses more on the
concrete instances of style, grammar, and usage. This document should be
user-friendly for the non-technical writer.  Focus more on the fundamentals
of how readers understand documents--focus less on some of the smaller
details of technical communication (a beginning of this is in the LDP
Reviewer's Guide).  Example:  We don't have to eradicate contractions, but
we do need to standardize how and when we use terms.  We don't need to
alleviate personal experience, but we do need to make comments relevant to
the procedure.
* Make the document public for writers to consult. We have it there as a
reference; we suggest they use it; we don't shove it at them.
* Use the Style guide as a reference when editing new documents that come
into the site. (This places the responsibilty for the document on the
reviewer, but with the style guide being pared down, this should be
manageable. We don't have to make it into a corporate document, but we can
make it more usable and easier to understand.)
* When there appear to be areas of the style guide that need updating--we
update the guide. We make the style guide a living document instead of a
dead set of standardized rules.


If this is folded into the review process, I will be more than happy to
lead a team to come up with a pared down, functional, useful style guide
that focuses on the fundamentals of easy-to-use documentation.

Thanks,

joy



             Joy E. Yokley
Linux Information Development
IBM Linux Technology Services
              512-838-4118


             Joy E. Yokley
Linux Information Development
IBM Linux Technology Services
              512-838-4118

Subject: Re: Style Guide
From: Randy Kramer ####@####.####
Date: 5 Jul 2001 17:27:09 -0000
Message-Id: <3B44A1B9.15DD@fast.net>

Joy E Yokley wrote:
> A possible plan of action:
> 
> * Develop a pared down version of the style guide that focuses more on the
> concrete instances of style, grammar, and usage. This document should be
> user-friendly for the non-technical writer.  Focus more on the fundamentals
> of how readers understand documents--focus less on some of the smaller
> details of technical communication (a beginning of this is in the LDP
> Reviewer's Guide).  Example:  We don't have to eradicate contractions, but
> we do need to standardize how and when we use terms.  We don't need to
> alleviate personal experience, but we do need to make comments relevant to
> the procedure.
> * Make the document public for writers to consult. We have it there as a
> reference; we suggest they use it; we don't shove it at them.
> * Use the Style guide as a reference when editing new documents that come
> into the site. (This places the responsibilty for the document on the
> reviewer, but with the style guide being pared down, this should be
> manageable. We don't have to make it into a corporate document, but we can
> make it more usable and easier to understand.)
> * When there appear to be areas of the style guide that need updating--we
> update the guide. We make the style guide a living document instead of a
> dead set of standardized rules.

Sounds good to me, and very appropriate!

On a related but slightly different topic, I would have liked to see
more examples in the section with the grammar rules -- some of them
would benefit from an example.  (Just went to look for the ones where I
had problems -- don't notice them now except I need a definition of
appositive.)  I think if the guide goes to the trouble of listing the
rules of grammar to be followed, it should make an effort to make them
understandable to the anticipated audience, which is not only english
majors.

Other comments on the document:

-The rules say "Do not use apostrophes to denote contractions", and I
should probably recognize that the overriding rule is don't use
contractions, but the rule is confusing.  If you do break the rule and
use a contraction, do you write "dont" or "don't" or what?

-The section "Top 10 Topics to Watch Out For" contains a mixture of good
and bad characteristics.  Sometimes it is not clear to me which is
which, for example, in "Topics described in sequential paragraphs rather
than in tables", which is preferred, paragraphs or tables?  (Aside: Does
"Top 10 Topics to Watch Out For" satisfy all the rules of grammar?)

regards,
Randy Kramer
Subject: Re: Style Guide
From: David Merrill ####@####.####
Date: 6 Jul 2001 00:23:04 -0000
Message-Id: <20010705202223.G12263@lupercalia.net>

On Thu, Jul 05, 2001 at 01:19:31PM -0400, Randy Kramer wrote:
> On a related but slightly different topic, I would have liked to see
> more examples in the section with the grammar rules -- some of them
> would benefit from an example.  (Just went to look for the ones where I
> had problems -- don't notice them now except I need a definition of
> appositive.)  I think if the guide goes to the trouble of listing the
> rules of grammar to be followed, it should make an effort to make them
> understandable to the anticipated audience, which is not only english
> majors.
> 
> Other comments on the document:
> 
> -The rules say "Do not use apostrophes to denote contractions", and I
> should probably recognize that the overriding rule is don't use
> contractions, but the rule is confusing.  If you do break the rule and
> use a contraction, do you write "dont" or "don't" or what?
> 
> -The section "Top 10 Topics to Watch Out For" contains a mixture of good
> and bad characteristics.  Sometimes it is not clear to me which is
> which, for example, in "Topics described in sequential paragraphs rather
> than in tables", which is preferred, paragraphs or tables?  (Aside: Does
> "Top 10 Topics to Watch Out For" satisfy all the rules of grammar?)

Would you please forward your comments to the authors? I'm sure they
would appreciate the feedback. And while we're at it, I'll let the
gnome-doc list know that we like their doc and would like to use it at
least in part. I'm sure they won't mind, but it's polite to ask.

And, FYI, I wrote a small section for the LAG on style issues. It is
pretty poor in comparison to this guide, but it does address a few
issues this guide doesn't. Let's make sure we fold anything from there
into this guide if we actually implement it.

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

It is practically impossible to teach good programming style to students
that have had prior exposure to BASIC: as potential programmers they are
mentally mutilated beyond hope of regeneration.
		-- Edsger W. Dijkstra, SIGPLAN Notices, Volume 17, Number 5
Subject: style guide
From: Rahul Sundaram ####@####.####
Date: 23 Aug 2004 14:43:44 -0000
Message-Id: <20040823144342.39017.qmail@web8509.mail.in.yahoo.com>

Hi

Please consider adding this link to the author guide
or resource section in tldp.org

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

Though some of it are specific to gnome the guide in
general is pretty useful. I believe new authors would
want to take a good look at it

regards
Rahul Sundaram




	
		
__________________________________
Do you Yahoo!?
New and Improved Yahoo! Mail - 100MB free storage!
http://promotions.yahoo.com/new_mail 
Subject: Re: style guide
From: "G Ferguson / LDP" ####@####.####
Date: 23 Aug 2004 18:22:13 -0000
Message-Id: <20040823182151.8B3B641484@mail01.powweb.com>

> Please consider adding this link to the author guide
> or resource section in tldp.org
>
> http://developer.gnome.org/documents/style-guide/

We already have it listed/referenced in the very first bullet.
http://www.tldp.org/authors/index.html#resources

-- 
Greg Ferguson / LDP volunteer
####@####.####
[<<] [<] Page 1 of 1 [>] [>>]


  ©The Linux Documentation Project, 2014. Listserver maintained by dr Serge Victor on ibiblio.org servers. See current spam statz.