discuss: Proposed: Author-Mini-Howto (full text)
Subject:
Proposed: Author-Mini-Howto (full text)
From:
David Lawyer ####@####.####
Date:
31 May 2008 07:30:55 +0100
Message-Id: <20080531063753.GE2054@davespc>
Here's my proposed short Author-HOWTO (mini). It's in linuxdoc source
but fairly easy to read. I thought that there were no objections to
this about 1 1/2 years ago when I wrote it. But I submitted it and
nothing happened. So now I'm starting over. Please comment on it.
New authors would be pointed to this if they want to get started
quickly. The Author Guide would still be valid too, but in case of a
conflict, this mini-howto would prevail (until the Author Guide can be
revised). What do you think?
David Lawyer
<!doctype linuxdoc system>
<article>
<title>Author-Mini-Howto
<author>David S. Lawyer
<tt><url ####@####.####
<date> v0.1, May 2008 (Orig. January 2007)
<p>If you would like to become a Linux Documentation Project author, read
on. First 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 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:
####@####.#### and ask for a review (note any previous reviews).
We will read it over and if it looks OK, it gets put into our
collection.
<em>Markup</em>
<p>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.
<url url="http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html"
name="The LDP HOWTO Generator">
Here are links for details of the two possible markups:<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"><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>
<em>Guidelines for Writing a HOWTO, etc.</em>:
<p>Detailed guidelines may be found in <url
url="http://www.linux.ucla.edu/LDP/LDP/LDP-Author-Guide/html/index.html"
name="LDP Author Guide">.
<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 are 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), or <url
url="http://www.gnu.org/copyleft/fdl.html" name="GNU Free
Documentation License"> (without invariant sections).
<em>Feedback</em>
<p>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.
<!--
<em>Author's notes. A comment in the sgml source</em>
<p>There is 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?
-->
</article>
