discuss: One-page replacement for LDP-Author-Guide (not exactly, but ...)
Subject:
One-page replacement for LDP-Author-Guide (not exactly, but ...)
From:
David Lawyer ####@####.####
Date:
29 Apr 2003 22:52:00 -0000
Message-Id: <20030429225206.GA880@lafn.org>
I've just rapidly written a one-page replacement for the
LDP-Author-Guide. The Guide is far too long and is intimidating for
most people that are thinking of writing a HOWTO, etc. It may take
longer to read the Guide and digest it than to write a short HOWTO.
My one-pager is not exactly a replacement since it points to the Guide if
the reader wants to use DocBook. If the choice is LinuxDoc it point to
my Howtos-with-LinuxDoc mini. If this one-pager is accepted, then I'll
revise the mini so that infomation which duplicates info in the
one-pager can be skipped over.
My one-pager is based on Tim Bynum's work which was based (to some
extent) on previous stuff. But I'm sure he won't mind my using it
without credit (it's mostly my stuff anyway). A link to this one-pager
would be in the Author / Contribute section of our main webpage. Or it
could be in Contribute/ Help (or better yet, in both). Perhaps
"Contribute / Help" could be renamed "Volunteers Wanted". A plug for
helping with reviews should be in here somewhere.
David Lawyer
PS:
Here's my one-pager. I know that my date format conflicts with the
Guide but I think it's better. Note this is only a first draft, but I
strongy feel that something short like this is needed that will also
offer the option of LinuxDoc if they are in a hurry.
--------------------------------------------------------------------------
Writing a LDP document by David S. Lawyer
The LDP need more 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 documentation. Post your intentions
to: ####@####.#### so that we know what you are up to. When
you've finished writing, submit it to: ####@####.#### We'll
read it over and if it's OK it gets put into our collection. Read the
Guidelines below.
Guidelines for Writing a HOWTO, etc.:
*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.
*You must use a markup language, either LinuxDoc or DocBook.
LinuxDoc is by far the easiest to use and learn but it's not nearly
as advanced as DocBook. For LinuxDoc see the mini-HOWTO:
Howtos-with-LinuxDoc. For DocBook see the LDP-Author-Guide. Writing
in such a markup language allows us to convert your writing into
webpages (html), plain text, and other formats. To insure that your
markup is done correctly, you should try to convert it into plain
text and html on your Linux PC. Your could use another HOWTO as a
model (template).
Fix-me: add urls above.
*You will own the copyright to what you write but you must select a
license that meets this 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." You could use the boilerplate
license in the Manifesto, the GFDL license, or the Open Publication
License (without options A or B).
Fix-me: add urls above.
*Make sure that all of the information is correct. When in doubt,
investigate. If necessary, make it clear to the reader that you are
not completely sure.
*Make sure that your name, email address, date, and a version
number is near the beginning of the document. The standard header is
for example:
The Linux-System-HOWTO
by John Doe ####@####.####
v2.10.29, 31 May 2003
*Readers of your HOWTO will email you questions and suggestions.
These should be helpful in maintaining your HOWTO (which you need to
do to keep it up-to-date). 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 spam, which can be mostly filtered out. Scrambling your
email address to avoid spam will not permit others to email you with
just a click of the mouse. I don't recommended it, but do it if you
must.
