Author-Mini-Howto

David S. Lawyer mailto:dave@lafn.org

v0.1, May 2008 (original. January 2007)

The Linux Documentation Project needs authors to write free documentation. If you think you can explain things OK and might like to become an LDP author, first pick a Linux topic that lacks good, free, or up-to-date documentation. Post your intentions to: discuss@en.tldp.org. But first visit http://lists.tldp.org to subscribe to this discuss list. If no one responds to your post, then try again or just start writing.

If there is already a LDP document on your proposed topic but it needs updating/improving, email the author. If the author does not have time to update it or cannot be located, then consider updating it yourself. Make sure you do not violate the license without the author's permission. Also, email the discuss list.

When you have finished writing, try to find others (possibly on the discuss list) to read it over for suggestions. Finally, submit it to: submit@en.tldp.org and ask for a review (note any previous reviews). We will read it over and if it looks OK, it gets put into the Linux Documentation Project collection.

Markup

LDP docs are in a markup format (something like HTML) using either LinuxDoc or DocBook markup. LinuxDoc is by far the easiest to use and learn but DocBook has many more markup tags. Howtos use the "article" type of markup. Or you can write it in some other format (such as plain text) and try to find someone to help convert it to LinuxDoc or DocBook by requesting this on the discuss list. But future updates you make must be in one of these two approved formats and unless you already know DocBook it will be easier to update if it is LinuxDoc. One way to get started is to copy the marked up version of someone else's Howto and then modify it so that it becomes your Howto.

Writing in such a markup language allows us to convert your source doc (in DocBook or Linuxdoc) into webpages (html), plain text, and other formats. To insure that your markup is done correctly, you should try converting it yourself into html etc. before submitting it.

If you want to start writing immediately, then you may use a "fill in the blanks" template which will generate LinuxDoc formatted output. The LDP HOWTO Generator

Here are links for details of the two possible markups:
For DocBook see LDP Author Guide
For LinuxDoc see: Howtos-with-LinuxDoc

Guidelines for Writing a HOWTO, etc.:

Detailed guidelines may be found in LDP Author Guide

Copyright

You will own the copyright to what you write but you must select a license that meets the criteria in the Manifesto: "Anyone may copy and distribute (sell or give away) LDP documents (or other LDP works) in any media and/or format. No fees are required to be paid to the authors. It is not required that the documents be modifiable, but it is encouraged." Some license that are OK to use are: The Boilerplate License in the Manifesto or Creative Commons Attribution-ShareAlike License, or Open Publication License (without options A or B), or GNU Free Documentation License (without invariant sections).

Feedback

Readers of your HOWTO will likely email you questions and suggestions. These should be helpful in maintaining your HOWTO. But you are under no obligation to provide free support to people with problems, especially if the problem is beyond the scope of the HOWTO or is poorly described. You are also likely to get more spam, which can be mostly filtered out. Scrambling your email address to avoid more spam is one option, but it will make it more difficult for readers to email you.