Subject:
Re: Draft of "Writing a LDP Document"
From:
Emma Jane Hogbin ####@####.####
Date:
27 Jan 2005 21:35:20 -0000
Message-Id: <20050127211957.GD5896@smeagol>
David,
Thank you for providing this summary. It was originally proposed that your
document would replace the content on www.tldp.org/authors/
http://lists.tldp.org/index.cgi?10:mss:2194:200404:klmejakjjdnnakcpejbj
There are still some things that should be cleared up though...first off,
can we please not refer to it as a "guide"? According to our own
description, a guide is a "longer, in-depth book." This is not a guide!!
It's a HOWTO or a summary or an anti-Guide. ;)
In general contractions (we'll, etc., you've) should be expanded to their
full English words. They are more difficult for our readers who do not have
English as their first language.
On Tue, Jan 18, 2005 at 02:25:00PM -0800, David Lawyer wrote:
> 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.
"note any previous reviewS" .... the s is missing.
> <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
This is not entirely true. We have many authors who write in something
else and convert to DocBook before sending us their documents. There are
also text-to-DocBook conversion tools. I have included some of them here:
http://www.tldp.org/LDP/LDP-Author-Guide/html/x2docbook.html
I think Tille is also working on a detailed set of instructions for some
of the ones that I have not yet included. Of course I write DocBook
natively and would love it if everyone else did, but I'd rather people
write GOOD documents than waste time trying to write any kind of markup.
> 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.
I wouldn't use "try to find" as I don't think we've had m/any documents
that we were unable to get converted to DocBook.
> 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).
Well ideally they'd validate the document....not just try to convert it.
There's a very small chance that their conversion tools will be identical
in set up to what Greg uses on the server.
> 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.
Please take out the sentence, "But it isn't required reading." It is
sufficient to say, "Detailed guidelines are in..." those who want to read
the detailed version will, those who do not want to read it won't read it.
> <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.
Heh. Omit "etc." For some people that is jargon. ;)
> <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).
Please add the GNU FDL.
> <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,
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 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.
That's fine. I don't think that CVS information should be included in this
document.
> 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?
Yes, we will find someone to do the conversion. There are also tools that
will convert most formats into something that we can use.
emma
--
Emma Jane Hogbin
I18N Coordinator, The Linux Documentation Project
www.tldp.org
