4. Writing and Submitting a HOWTO

If you are interested in writing or maintaining a HOWTO, please get in touch with us FIRST!!! at ldp-discuss@lists.linuxdoc.org.

If you want to maintain a unmaintained HOWTO, please also get in touch with the former author.

Here are a few guidelines that you should follow when writing a HOWTO:

• 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 language.
• If you are writing a HOWTO, you must use the SGML-Tools package, available from http://www.sgmltools.org/, to format the HOWTO. This package allows us to produce HTML, LaTeX (for DVI and PostScript), plain text and DocBook sgml 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 HTML.
• 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 software can be downloaded from (FTP site name, full pathname), and the current version number and release date of the software.
• Include an FAQ section at the end, if appropriate. Many HOWTO documents need an ``FAQ'' or ``Common Problems'' section to cover information which can't be covered in the regular text.
• Use other HOWTOs a model! The SGML source to the HOWTOs is available on Linux FTP sites. In addition, have a look at the Using DocBook Guide, the HOWTO-HOWTO, the LDP manifesto and the LDP license guide.
• 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. The standard header is:

          Title
          Author's name and email address
          Version number and date
          
  

  for example:

          The Linux HOWTO Index
          by Tim Bynum
          v2.10.29, 31 July 1997
          
  

• Lastly, be prepared to receive questions and comments about your writing. There are several hundreds of accesses to the HOWTO collection every day from around the world!

After you have written the HOWTO, mail the SGML source to us at ldp-submit@lists.linuxdoc.org.

It is important that you go through us when submitting a HOWTO, as we maintain the archives 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.