discuss: re:One-page replacement for LDP-Author-Guide (not exactly, but ...)
Subject:
re:One-page replacement for LDP-Author-Guide (not exactly, but ...)
From:
Greg Ferguson ####@####.####
Date:
30 Apr 2003 01:00:57 -0000
Message-Id: <200304300100.h3U106pJ069018@hoop.timonium.sgi.com>
On Tue, 29 Apr 2003 15:52:06 -0700 David Lawyer ####@####.#### wrote:
> 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.
Now we have the LDP Author Guide, the LDP-FAQ and this. Just pointing
that out. Can we maybe put this *in* the LDP author guide as a
"quick start" appendix (something like that) and refer to it from
other areas of the site?
>
> David Lawyer
> PS:
> Here's my one-pager. I know that my date format conflicts with the
> Guide but I think it's better.
YYYY-MM-DD (ISO 8601). Let's keep it a standard.
My comments/"info to add" is interspersed. Feel free to wordsmith it
accordingly.
> 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.
Your document will be added to our list of works "in progress". If
you have an available draft, please provide a pointer (or submit
the file so that we might reference the draft off the aformentioned
list).
> When you've finished writing, submit it to: ####@####.#### We'll
> read it over and if it's OK it gets put into our collection.
We also provide CVS access to our central repository of all source
files. It is recommended, but not required, that you maintain your
document through the use of our CVS tree (an account must be requested).
Document updates can still be sent through the 'submit' email address
if CVS access is not utilized.
> 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.
The LDP supports the following markup/versions:
Linuxdoc SGML; DocBook SGML v4.2, v4.1 or v3.x; and
DocBook XML v4.2 or v4.1.2
> 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.
Sample templates and other tools/pointers/documentation can be
found in our Author's Resources area - http://www.tldp.org/authors/
> *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.
Fix-me: add specific verbage, or refer to the verbage which is
found in the existing template files.
> *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
(Fix-me: date format)
If possible, include "HOWTO" in the title. Write a short, concise
abstract which informs the user as to the content of the document.
Filenames should be descriptive, utilizing "-HOWTO" in the filename:
e.g. Linux-System-HOWTO.xml
For those utilizing DocBook, we suggest keeping a revision history
with the document. Refer to the DocBook quick reference for a
sample (or the LDP template files for DocBook).
When in doubt, or if questions arise contact ####@####.####
> *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.
