Writing and Maintaining a Linux HOWTO ------------------------------------- This document describes what's required to write and maintain a Linux HOWTO. Linux HOWTO documents are a collection of short (usually under 20 pages) papers on doing various things with Linux. Examples include the Installation HOWTO, Mail HOWTO, and Busmouse HOWTO. HOWTOs are generally more comprehensive than FAQs, but if you wish to write your document as an FAQ that's fine. The Linux HOWTO maintainer is Greg Hankins (gregh@sunsite.unc.edu). I take care of archiving, formatting, and posting all of the HOWTOs. This is to save you (the writer) the trouble of doing this. All that you have to do is mail me your HOWTO whenever you make updates. I do all of the dirty work (with a lot of Perl magic to help me). Here are the steps required to write, submit, and maintain a Linux HOWTO. 1.) Present your idea. The first step is to come up with an idea for a new HOWTO. You might want to ask around, on the newsgroups or mailing lists, for suggestions and ideas for topics to cover. Note that I'd rather not see any HOWTOs which overlap in content. If you would like to write information about using SLIP, that's covered in the NET-2-HOWTO, and you should talk to the maintainer of that document about including your information there. This is to reduce confusion; I'd rather most of the HOWTOs have content independent of others. We have made exceptions to this, however. For example, the Ethernet HOWTO, which talks about all of the hardware driver issues associated with using Ethernet cards, could technically be part of the NET-2-HOWTO. However, the Ethernet HOWTO is quite long, and the information specialized enough that you can read the Ethernet HOWTO without the NET-2-HOWTO. If your HOWTO would have overlapping content, let's talk about it first. Once you have your HOWTO concept ready, just mail it to me (Matt Welsh). You don't have to do anything formal for this; just a note saying what you'd like to do and what the HOWTO would be about. I'll suggest a possible title for the archive filenames, and you're ready to write. The only reason I'd like to see your proposal before you write a HOWTO is in case another, similar HOWTO is already underway, or if your idea would conflict with another project. Don't sit down and write a 30-page document before you're sure that it'll be included in our archives! 2.) Write the HOWTO. HOWTOs don't follow any special formatting convention, with the following exception: They must be available in plain ASCII. You can use whatever text tools you like: You can write the HOWTO using nroff, texinfo, or just as a plain ASCII file. As long as you can produce plain ASCII I'm happy. TeX or HTML source does *not* count as "plain ASCII"; what I mean by this is anything that can be read without special tools, anything that does not require formatting by the reader to use. Many of the HOWTOs use the Linuxdoc-SGML formatting package, found on ftp.cs.cornell.edu:/pub/mdw This package allows you to write your HOWTO as a single source file (in a simple an SGML-derived language), and produce HTML, LaTeX, and plain ASCII (via groff) from it. It's easy to learn and use, and greatly simplifies writing documents to be produced in multiple formats. Unless you have a strong aversion to this idea all new HOWTOs should be written with this package. It makes my life easier, too, because I format the HOWTOs for you with Linuxdoc-SGML. The Linuxdoc-SGML package includes a user guide which tells you exactly what you need to do. Please include an explicity copyright notice with your HOWTO. Note that the HOWTOs are published and distributed by several publishing companies; this is important both to them and to the LDP (as most of these companies donate funds to the LDP in return!). I suggest using a copyright notice such as the following: > Unless otherwise stated, Linux HOWTO documents are copyrighted by their > respective authors. Linux HOWTO documents may be reproduced and distributed > in whole or in part, in any medium physical or electronic, as long as > this copyright notice is retained on all copies. Commercial redistribution > is allowed and encouraged; however, the author would like to be notified of > any such distributions. > > All translations, derivative works, or aggregate works incorporating > any Linux HOWTO documents must be covered under this copyright notice. > That is, you may not produce a derivative work from a HOWTO and impose > additional restrictions on its distribution. Exceptions to these rules > may be granted under certain conditions; please contact the Linux HOWTO > coordinator at the address given below. > > In short, we wish to promote dissemination of this information through as > many channels as possible. However, we do wish to retain copyright on the > HOWTO documents, and would like to be notified of any plans to redistribute > the HOWTOs. > > If you have questions, please contact Greg Hankins, the Linux HOWTO > coordinator, at gregh@sunsite.unc.edu via email, or at +1 404 853 9989. Making your copyright more restrictive could make it difficult for the HOWTOs to be published. Consider your HOWTO a contribution to the Linux community; we want these things to be distributed as widely as possible. 3.) Submit your HOWTO. Once the HOWTO is written, just send it to me (gregh@sunsite.unc.edu). If you have used Linuxdoc-SGML, just mail me the SGML source file for the HOWTO. (Don't send me anything else; I take care of formatting the HOWTO from your source file.) If you have used another text tool, just send me the formatted plain ASCII for the HOWTO. If you use a text processor other than Linuxdoc-SGML I can't format the HOWTO for you, nor can I accept other formats (PostScript, HTML, whatever). The HOWTO formatting and archiving process is automated and handling these special cases is (currently) a pain. All I can accept is plain ASCII or Linuxdoc-SGML source. C'ect la vie. Once I get your HOWTO I'll drop it into my pool of "things to do". Hopefully this means that I'll format it and archive it within a week of receipt. I'm extraordinarily busy, so if you want your HOWTO to be updated urgently say so when you send it to me. 4.) Join the mailing list. There is a (private) mailing list for Linux Documentation Project writers. That's right---this includes HOWTO writers. It's important that you join this mailing list, because there we discuss issues such as changes to Linuxdoc-SGML, as well as how to use donations made to the LDP. To join this list, send mail to listproc@cornell.edu with the body subscribe ldp-l as in, subscribe ldp-l Norbert Ebersol Subscriptions to this mailing list are moderated; this means that I have to approve everyone who subscribes. Everyone on the list is an LDP writer. Regarding donations... several companies publish the HOWTOs either in bound or loose-leaf form. We consider this a great help to Linux users who don't have network access. Some of these companies donate a certain amount to the LDP for each book of HOWTOs that they publish. Sales of these books are quite impressive; at least several thousand a month at this point. Right now, all donations to the LDP are deposited in an account maintained by Michael K Johnson (author of the Kernel Hackers' Guide and all-around nice guy). Because the LDP is not (yet) an official organization, donations are usually made out to Michael or myself personally, but all donations are sent to this account. What we plan to do is allot the donation money to each LDP writer based on total page count contribution. That is, if the LDP has produced 1,000 pages of documentation, and you have written 100 pages of that, your share of the donations will be 10% of the total. Page counts will be based upon the LaTeX-formatted versions of the HOWTOs and LDP manuals, which have uniform page size and fonts. You can decide what to do with your share of the donations; we'll ask you what percentage you'd like to donate to various causes (such as the FSF, WINE project, and so forth) and what percentage you'd like to keep for yourself. In this way we can make one check out to the FSF from "the Linux Documentation Project" based on what everyone wants to contribute. We haven't yet ironed out this procedure, but will do so once we distribute the first round of donations. I'm open to suggestions! One of these days the LDP may incorporate as a non-profit organization. Unfortunately it's difficult to do this for an organization which lives in cyberspace. 5.) Maintain your HOWTO. The last step is to merely maintain your HOWTO; make periodic updates and send them to me, as above. The HOWTOs will be posted regularly to the Linux newsgroups, available on all of the FTP sites, and the LDP Web page at http://sunsite.unc.edu/mdw/linux.html So you should get plenty of comments from readers. Best of luck, and let me know if you have any questions. Greg gregh@sunsite.unc.edu