Chapter 8. Writing and Submitting a HOWTO

If you are interested in writing or maintaining a HOWTO, please contact us FIRST at [email protected]. If you want to maintain a unmaintained HOWTO, please try to contact the former author.

Consult the LDP Author Guide for detailed information on writing and submitting a HOWTO.

Here are a few general 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.

• Make sure that all of the information is correct. We 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, fullpathname), and the current version number and release date of the software.

• Include an FAQ section at the end, if appropriate. Many HOWTO documents need a ``FAQ'' or ``Common Problems'' section to cover information which cannot be covered in the regular text.

• HOWTOs should be submitted to us in either DocBook or linuxdoc SGML; or DocBook XML. Refer to the LDP Author Guide for further information.

• Use other HOWTOs a model. The SGML/XML source to the HOWTOs is available on Linux FTP sites. In addition, examine the LDP Author Guide, the LDP manifesto (and license guide), and the Using DocBook HOWTO.

• 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 postal mail address if you want. The standard header is: Title / Author's name and email address / Version number and date. For example:

  The LDP Sample HOWTO by various_authors v6.1, 2001-05-01

  Refer to the LDP Author Guide for further information.

• 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 [email protected].

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.

Please send the LDP periodic updates whenever appropriate.