discuss: Draft of very short Authors Guide
Subject:
Draft of very short Authors Guide
From:
David Lawyer ####@####.####
Date:
18 Jan 2005 23:08:29 -0000
Message-Id: <20050118222459.GC1402@lafn.org>
Here's my draft in LDP format.
<!doctype linuxdoc system>
<notes>
<title>DRAFT: Writing a LDP Document, by David S. Lawyer (Jan. 2005)
<date> Jan. 18, 2005
<p>The Linux Documentation Project (LDP) needs more volunteer writers
to document Linux for the benefit of the Linux community. What you
write will be put on hundreds of mirror sites throughout the world for
others to read (and download). Pick a Linux topic that lacks good,
free, or up-to-date documentation. Post your intentions to:
####@####.#### But first visit <url
url="http://lists.tldp.org"> to subscribe to the discuss list. If no
one responsds, 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. It the author doesn't have time
to update it or can't be located, then consider updating it yourself.
Make sure you don't violate the license without the author's
permission. Also, email the discuss list.
When you've finished writing, try to get others to read it over for
suggestions. This might happen if you send it (or a link to it) to
####@####.#### Finally, submit it to: ####@####.#### and
ask for a review (note any previous review). We'll read it over
and if it's OK, it gets put into our collection.
<em>Markup</em>
<p>LDP docs are in a markup format something like HTML. So your writing
should be in either LinuxDoc or DocBook markup. LinuxDoc is
by far the easiest to use and learn but it's not nearly as advanced as
DocBook. Use the "article" type of markup. Or you can just submit your
writing in plain text and LDP will try to find someone to markup your
original. But you'll have to do the markup yourself when you update
your doc in the future.
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 into say html before submitting it. You could use the
source for another HOWTO as a model (template).
Here's links for details of the two possible markups:<newline>
For <em>LinuxDoc</em> see: <url
url="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/Howtos-with-LinuxDoc.html"
name="Howtos-with-LinuxDoc"><newline>
For <em>DocBook</em> see <url
url="http://www.linux.ucla.edu/LDP/LDP/LDP-Author-Guide/html/index.html"
name="LDP Author Guide">
<em>Guidelines for Writing a HOWTO, etc.</em>:
<p>Detailed guidelines are in <url
url="http://www.linux.ucla.edu/LDP/LDP/LDP-Author-Guide/html/index.html"
name="LDP Author Guide">. But it isn't required reading.
<itemize>
<item>Use meaningful structure and organization, and write
clearly. Many of the people reading HOWTOs will not know English
well, so avoid jargon, etc. that they might not understand.
<item>Be sure that all of the information is correct. When in doubt,
investigate. If you're not sure about something, say so.
<item>Make sure that your name, email address, date, and a version
number (selected by you) is near the beginning of the document.
</itemize>
<em>Copyright</em>
<p>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: <url url="http://tldp.org/manifesto.html#s6" name="The Boilerplate
License in the Manifesto"> or <url
url="http://creativecommons.org/licenses/by-sa/1.0/" name="Creative
Commons Attribution-ShareAlike License">, or <url
url="http://www.faqs.org/docs/htmltut/oplicense.html" name="Open
Publication License"> (without options A or B).
<em>Feedback</em>
<p>Readers of your HOWTO will email you questions and suggestions.
These should be helpful in maintaining your HOWTO. But you are under
no obligation to provide free support for 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 is one option, but it will make it more difficult for readers to
email you.
<em>Author's notes. To be deleted before publication</em>
<p>There's no info about CVS here. After someone gets their doc
published on LDP, we then send them info on the CVS option.
I don't think we should continue to say that we will find people to
convert plain text to docbook (or linuxdoc). Linuxdoc is not much
more difficult than plain text. It forces people to put in a title,
date, etc and to organize it in sections and subsections. Suppose a
plain text doc is submitted and it's not clear how it is partitioned
into sections and subsections?
</notes>
