discuss: Style Guide
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
