Subject:
LDP Style discussion (cont.)
From:
"Joy Y Goodreau" ####@####.####
Date:
8 Apr 2002 18:26:09 -0000
Message-Id: <OFAD2FB970.84AA52E9-ON85256B95.006510FA@pok.ibm.com>
As we prepare to begin the Style Guide effort at the LDP, I thought it
important to answer some of the questions David Lawyer posted to the list
about the Style Guide in case many of you had the same questions. My
apologies for this being so late of a response. I also apologize for this
being so long. My passion for this project and for documentation that is
easy to read makes me somewhat of a zealot! :)
On Thur, Mar 21, 2002 at David Lawyer wrote:
>I think that most LDP authors are not really developers although many of
>them have done some programming or script writing. Developers write
>programs and then often document them in man pages, info pages and
>manuals that go into the documentation (doc) tree on most Linux
>computers. LDP authors generally write integrative documents that
>describe how to use a number of programs to accomplish a task. They
>seldom are the developers of such programs.
I think this is a fair delineation. Many of our authors are probably not
developers in the traditional sense. They are system administrators,
enthusiastic individuals who figure out how to work something and want to
tell others, experts in some area of Linux, or new users who can't find
documentation on something they figured out how to fix and want to share it
with the world. Some of them are developers of applications, but probably
not the majority.
>We need to make it easy for prospective authors to publish their work.
>Having a long style guide is something that most authors wouldn't want
>to use. I like the style guide in the old HOWTO-INDEX. It's just a
>paragraph long.
My argument precisely against many of the style guides in existence today.
They are not written for someone who is not a writer by profession. We
don't want that here. We want more of a style reference.
>So I don't think that we really need a style guide, at least not a long
>one. What I think is more important is to write a very short authoring
>guide based on linuxdoc-sgml. ....
I totally agree. No long, exhaustive style guide. I will leave the writing
of the authoring guide in linuxdoc-sgml to you. I know you are the leading
advocate for linuxdoc.
>If someone is really interested in style guides, there are a number of
>them available in libraries. It's been mentioned that there are guides
>for both KDE and Gnome and these should be available on the Internet.
>What is important is clarity, accuracy, and relevancy. It's not mainly
>style (but poor style can result in be unclear presentation).
>LDP shouldn't, in my opinion, try to teach people how to write. To
>become an LDP author, you are supposed to already know how to write,
>along with knowing how to use some kind of an editor or word processor.
A style guide's primary goal is clarity and accuracy--exactly what you are
arguing is important. Style is more than grammar and more than what
something looks like. For technical documentation, style is a matter of
usability. Style focuses on how easily what you write translates into other
languages. Style guides let authors know that when you have authors who
read English as a second language, they may get confused if you use certain
phrases or types of humor. Because our authors are not necessarily writers
by trade, it is essential that we provide a reference for them that helps
them make their documentation the most easily-read document it can be. I
have been reviewing some of the documents on the site and your assumption
that
>To
>become an LDP author, you are supposed to already know how to write,
>along with knowing how to use some kind of an editor or word processor.
is incorrect. The whole idea for the style guide and the review of
documentation on the site came about from working Linux World Expos where
multiple people would comment on what good information was up on our site,
but how stale it was and how hard some of it was to read. Granted, not all
authors will use the style guide, but it will be a reference available for
those who DO want to write better documentation.
>A major problem is that some people who are not native speakers of
>English tend to use the style of their native language. There's not
>much we can do about this except to have people review their work and
>help fix it.
Many English as second language writers do have problems with English
writing conventions. We hope that our review effort can catch the existing
documents and that a style guide will provide some point of reference for
those writers. However, I have also noticed that many non-native speakers
of English are better writers than English speakers because they are more
vigilant in their writing.
A final note, the style guide will not help those who don't read it. The
style guides on the other projects are complex and they enforce the rules.
They have editors who mark up documents and send it back to you for you
(the author) to do again until it meets the style. They do this for a
reason, they are trying to get quality documentation, and they want their
documentation to be as professional and uniform as possible. This is
nothing new. Those of us who are technical communicators are used to the
process.
We are not implementing this type of system at the LDP. For our purposes,
the style guide will provide a reference for those who are interested in
simple ways to make their writing better and more appropriate for technical
information. The style guide will also support the reviewers who are
reviewing documentation on the site. When we come to a document that is
hard to read, we can point the author to a reference that addresses the
problems of their document. If you are an author and your document is hard
to read, yes, we may point you to parts of the style guide that will
improve your document or we may ask you for permission to fix it ourselves.
There are so few of us though, that the main burden of quality for the LDP
documentation has to be born by the authors of the documents also. And
that is key, we can't just be interested in the number of documents on the
site, we have to also be interested in the quality of documents we give to
people in desperate need for information. I have been one of those people
searching the LDP looking for information. We cannot see ourselves only as
authors; we must think of the readers also.
I can always count on you, David, to be the advocate for making it easy for
the author. I am hoping that I can be your counter-point as the advocate
for the reader.
Joy Yokley Goodreau
Linux Information Developer
LDP Collections Editor
Ofc. (512) 838-4118
T/L 678-4118
####@####.####
