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 (
[email protected]).
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
[email protected] 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 (
[email protected]).
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
[email protected]
with the body
subscribe ldp-l <firstname> <lastname>
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
[email protected]
