[<<] [<] 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 [>] [>>] |