Joy Yokley Goodreau, the new collections editor for the Linux Documentation Project (LDP) has a
zestful enthusiasm for good HOWTOs. “Where some people groan at the thought of
technical documentation and think it is boring or dry, I love the idea of a
good, easy to read document,” says Goodreau. “I am very user-centered and
believe in trying to improve readers’ experiences with documentation. I believe
that we should make writing documents as simple as possible for the author, but
it is essential that readers have something they can work with.”The LDP has been around almost as long as Linux
has, serving as a resource for what everyone calls “HOWTOs:” how to
install, how to configure, how to compile, how to modify. For almost
10 years, volunteers have written docs, edited them, and maintained
them. Goodreau says that as Linux grows, the HOWTO reader becomes increasingly
more important. “We were one of the first and
only documentation repositories where Linux users could go and find
information to help them solve their problems,” Goodreau says. “As the years
have passed, more and more documentation is being written because Linux has more
users and more applications. We have been busy trying to keep up with the new
documentation and identify what gaps we still need to fill.”
In order to figure out what they have, what they need, and what needs to be
redone, she and colleague David Merrill are in the middle of
a major review effort. “We are trying to go through all the current documents on
the site and conduct a language and technical review for each one. One of my
goals is to implement a process where each document on the site is reviewed
regularly. We are not there yet, but we are making steady progress.
“I am also starting an LDP Style Guide effort,” she says. “Most guides are
written for experienced writers. They use arcane, grammatically correct but
counter-intuitive terms. Terms such as ‘gerund phrases’ or ‘dangling
participles’ are useless to new writers or writers who come to English as a
second language. We are planning a style guide for new writers that helps
them understand what issues to look for to make their documents easier to
read and translate to other languages. A common misconception about style
guides is that they are only about grammar; this may come from the way many
style guides are written. The style guide we are writing is more about
improving the reader’s experience: how to make the document easier to read
and easier to translate. Our audience is made up of developers, individuals
who solve technical problems, and system administrators who wish to write
about Linux issues. Our writers are not all English majors. I am hoping
that this customized style guide will be one more step to improving the
quality of the documents on the LDP.”
Because a large percentage of Linux users do not speak English, Goodreau is committed to the internationalization of the documentation project. “The Linux Documentation Project has been an excellent resource for the
Linux community in the past because there was nowhere else to go for
information. It was a grass-roots campaign by some very dedicated authors
and users who believed in Linux and wanted to share their fixes. We still
have that at the LDP, but now we are moving towards making this a truly
international repository. It is incorrect to think that all good
documentation is in English or that documentation will only be used by
readers of English. Linux is truly global.”
She also
works on keeping documents current by checking their update status. “If a document has not been updated in the past year, I request
the latest update from the author. If no update is available, the document
is evaluated. Depending on the involvement of the author, I might then
request that the author turn the document over to the LDP in order for us to
find a new maintainer, update the document, or archive the document.”
The project is always looking for more volunteers to author HOWTOs, maintain
them, or just suggest possible new documentation. The LDP stores its documents
in the DocBook format “because it generates multiple outputs, but authors
can submit to us in a variety of formats,” says Goodreau, including text and
HTML. LDP programmers have created a script that automatically structures
documents with DocBook tags, and eventually they hope to have a wiki-like
interface to make input and upkeep of documents even easier for authors.
Goodreau spends about 20 hours a week on the LDP. “I don’t think most people
realize how phenomenally committed the staff is,” she says. “Each of the staff
members has an area of expertise, and we are responsible for issues that fall
within that area. Yet, everyone is interested in every part of the backbone of the
organization. We don’t always agree, but we are very involved in the
process.
“I think the LDP represents some of the very best
of Linux.”
Category:
- Migration
