discuss: [jfleck@inkstain.net: GNOME Documentation Style Guide]
Subject:
Re: [jfleck@inkstain.net: GNOME Documentation Style Guide]
From:
"Ami M. Echeverri" ####@####.####
Date:
3 Jul 2001 23:38:44 -0000
Message-Id: <3B4257A2.4DF2A946@pollywog.com>
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/
