If you are interested in writing a Pił HOWTO, please get in touch with
me first. Here are a few guidelines that you should follow when writing a Pił
- Try to use meaningful structure and organization, and write clearly. Remember
that many of the people reading HOWTOs do not speak English as their first
- If you are writing a HOWTO, you must use the SGML-Tools package, available
from http://www.pobox.com/~cg/sgmltools, to format the HOWTO. This package
allows us to produce LaTeX (for DVI and PostScript), plain text, and HTML from
a single source document, and was designed specifically for the HOWTOs. This
also gives all of the HOWTOs a uniform look. It is very important that you
format and review the output of the formatting in PostScript, plain text and
- Make sure that all of the information is correct. I can't stress this enough.
When in doubt, speculate, but make it clear that you're only guessing.
- Make sure that you are covering the most recent version of the available
software. Also, be sure to include full instructions on where additional software
can be downloaded from (FTP site name, full pathname), and the current version
number and release date of this software.
- Include an FAQ section at the end, if appropriate. Many HOWTO documents
need an ''FAQ'' or ''Common Problems'' section.
- Make sure that your name, email address, date, and a version number is
near the beginning of the document. You could also include WWW addresses and
a snail mail address if you want. Best is to use LYX textprocessor and the
LinuxDoc template. The standard header is:
- Author's name and email address
- Version number and date
- for example:
- The Pił HOWTO project
- Holger Zimmermann (firstname.lastname@example.org)
- V1.1 01 August 1998
- A short introduction to the Pił HOWTO project and the contents of the HOWTOs
Lastly, be prepared to receive questions and comments about your writing.
- After you have written the HOWTO, mail it to me. If you used SGML-Tools,
simply mail me the SGML source; I take care of formatting the documents. I'll
also take care of archiving the HOWTOs and posting them to the mailing list.
- It is important that you go through me when submitting a HOWTO, as I maintain
the archive and need to keep track of what HOWTOs are being written and who
is doing what.
- Then, all you have to do is send me periodic updates whenever appropriate.