Writing Documentation for Linuxconf

Linuxconf Needs Documentation

The linuxconf project is an extremely capable interface for configuring a Linux system. Plenty of system administrators use it. Unless you enjoy editing configuration files by hand (and some people do), linuxconf just makes things easier.

While an experienced sysadmin may not need documentation to use linuxconf, people who are new to Linux will need guidance. And even experienced linuxconf users may need to check the docs once in a while.

This is where the documentation effort begins. Actually, I shouldn't say "begins," since most of the help screens for linuxconf already exist. However, some are missing, some aren't complete, and some could be better. To see a list of linuxconf's help screens, use this command:

linuxconf --helpfiles

A list of all of the help files will scroll by. A *** appears by any that are missing. Another place to look is the list of missing help screens, but be aware that this list may not be completely up-to-date.

Take a look through the list of missing helpfiles. If you have some expertise in a certain area, write that help file. If you have used a particular help file, but you think it needs more information on a particular topic, write up just that piece.

If you don't think of yourself as a good writer, don't let that stop you. Send your efforts to Carole Williams (carole@redhat.com), who is waiting by her computer for your contributions. She can take care of spelling, grammar, punctuation, formatting, and any other administrative issues.

What Should Be Included in a Help File

The perfect help file answers all of the questions a linuxconf user has when they're looking at a particular screen. Obviously, documentation can't always be perfect, because documentation writers aren't mindreaders! Linuxconf documentation needs to at minimum cover the specific details of linuxconf screens, but also needs to provide background for any larger issues that affect configuration of Linux systems.

If you're writing a help file, try to address every parameter (buttons, checkboxes, menus, choices, boxes that need to be filled in) that the user sees on the linuxconf screen. Even if something seems obvious, one line of explanation won't hurt. Remember that certain help files show up in response to more than one help screen, so you may need to address several linuxconf screens with one help file.

In addition to providing the step-by-step instructions needed for a particular task, a good help file also addresses the big picture issues. General advice on configuring a Linux system to do a particular task will be very beneficial to new Linux users. Expert advice on complicated configurations or specific situations will be useful to more expert users.

Writing an explanation of how something works can be difficult. (Try writing up a linuxconf help file and you'll understand what I mean.) Examples can be extremely helpful, though, and are often more useful than all of the explanations in the world.

If you've successfully set up a complicated configuration on your system using linuxconf, and you think your experience would be helpful to other people, write it down. Even if you don't want to write a complete help file, you can send in your notes to carole@redhat.com, who will try to put them to good use. If you don't want to write a help file, you could instead write a HOWTO-style document on how to use linuxconf to accomplish a particular configuration of Linux.

There are a few things to keep in mind when you're writing documentation for linuxconf. Linuxconf is used on different flavors of Linux, and the documentation needs to avoid a bias towards a particular distribution. (If you're only familiar with one distribution, however, don't let that stop you from writing a help screen.) Also remember that linuxconf has several different interfaces (text mode, GUI, Web), so the documentation needs to be generic when describing aspects of the interface.

Whatever your expertise is, if you use linuxconf regularly, you can help in the documentation effort. All the documentation contributed to this product is considered public domain or covered under the GPL. Anyone who contributes a help file to linuxconf is encouraged to use the <author> SGML tag to provide their name and e-mail address. If you provide this information, then readers know who to e-mail in order to comment on the help. However, if you don't want to provide that information, you don't have to. If you'd like to contribute, and you'd like to receive some credit for your contributions, but you don't want to include your name in a help file, you can be included in the Documentation Roll of Honor.

How to Format a Help File

Linuxconf documentation is written using the Linuxdoc DTD (Document Type Definition), which uses SGML-tools. Information on how to write a Linuxdoc SGML document is available from the HOWTO HOWTO provided by the Linux Documentation Project (LDP). The information about translating help screens included on this site also provides information about formatting Linuxdoc documents.

What To Do with Documentation You've Written

Once you've written a help file for linuxconf, the first thing you should do is get feedback. You have several choices. If you have friends or colleagues who use linuxconf, get them to take a look at it. I'd also encourage you to submit a finished help file to the linuxconf mailing list, to get feedback from the extremely knowledgeable and helpful linuxconf users who read that list. Of course, the final technical review of the help file will be done by Jacques Gélinas (jack@solucorp.qc.ca).

If you want feedback on the formatting, the spelling, the grammar, any of the administrative aspects of the help files, or if you have a question and you just don't know who to ask, please feel free to e-mail Carole Williams (carole@redhat.com), the documentation coordinator for linuxconf.

If you're completely comfortable with the technical details and the formatting of the help file, send it in to Jacques (jack@solucorp.qc.ca).

What's in It for You?

Is writing documentation for an open source project a thankless job? Sometimes it seems that way. Existing open source documentation is often criticized and the lack of documentation surprises and alarms some users, but not many people line up to fix the problem.

This is where you could come in. The rewards: aiding in the success of linuxconf and Linux; helping people who are new to linuxconf (and possibly lowering the number of newbie questions posted to the linuxconf list); sharing your expertise with the world. In short, personal satisfaction. If you'd like to contribute to an open source project, but you're not a programmer, this is your chance. (Of course, programmers are also encouraged to write documentation, too.)

If a little public recognition would help, I'd like to post your name here, on the "Documentation Roll of Honor." So if you've contributed to linuxconf documentation and you'd like to be recognized here, e-mail carole@redhat.com.

This page maintained by Carole Williams. Please e-mail carole@redhat.com with any comments or criticisms about this page. Last updated on 11/8/99.