Subject:
Re: Draft of very short Authors Guide
From:
doug jensen ####@####.####
Date:
29 Jan 2005 19:52:54 -0000
Message-Id: <20050129195213.GA25570@debian>
Hi,
David, your document looks good to me. The documentation that I like
the most is generally short but complete and easy to comprehend. There
are a couple of suggestions that I have included within the text of your
document, but first a proposal that you might have already thought
about.
It might be useful to render the main document in source format. That
way the reader will immediately see just how simple the markup is. Add
a short paragraph at the top or near the top, that says that the
document has intentionally been left in source (linuxdoc) form and that
the same document in a converted form is in the appendix. Also, maybe
mention and include a short appendix defining the markup tags that are
used. Try to include the minimium set of markup tags that you believe
are needed for a basic document, both within your document and in the
appendix. That way the new author can use your document to learn what
to do and how to do it.
It might also be useful to include an appendix, in the same -short-
style, that describes the minimuim set of tools required to render the
document as html. Hopefully, also including brief notes on how to use
those tools.
As noted above I will now add some suggestions for the document itself.
Remember these are just suggestions, you will need to decide how to fit
them in, if you decide to use them.
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
Put in all the tags that you want the reader to be aware of, including a
scrambled email address, if you like. Also, select a license for your
document. And, version number?
>
> <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
Change "It the author" to "If the author"
> 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.
(The license should not be violated even with the author's permission
:). )
Change the "violate" sentence to something like; If the license doesn't
allow modification without the author's consent, you need to respect
that. Licenses that allow modification are strongly encouraged.
>
> 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
Change "This might" to "This hopefully will"
> ####@####.#### 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.
Change "into our collection" to "into the Linux Documentation Project
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
Maybe not necessary, but "article" could use a bit more definition.
Although, I can imagine that the definition may be too complex to
include gracefully.
> 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.
Add - Please plan on keeping your document updated, or find a compentent
person to do it for you.
>
> 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).
Change "source for another HOWTO" to "source code from another HOWTO"?
>
> Here's links for details of the two possible markups:<newline>
Change "Here's links" to "Here are links" ("These links provide...")
(Also, David, your short appendix, should you decide to include one.)
> 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.
Change "etc." to "and abbreviations"
> <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
Uhm, can that be 'strongly encouraged'
Change "Some license" to "Some licenses"
> 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).
I would also vote for the GFDL (without invariants, if possible), and
the GNU GPL (yes, I know, but it is a very useful license).
>
> <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
Add - Something like: (see my scrambled email address above)?
> is is one option, but it will make it more difficult for readers to
Change "is is" to "is".
Change "will make it" to "may make it".
> 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?
I agree. Although it may be possible to adequately review a document
that starts out as an unorganized/unstructured mass. It is difficult to
suggest content changes when the document also needs structural changes.
It becomes confusing and frustrating to both the author and reviewer,
because once the structure changes are made, the content may need to be
revised again. It can become difficult to produce a quality document
even if the author and reviewer give their best effort. If the policy
of the LDP is going to be *we will* accept any document and mold it into
a quality HOWTO, then those saying the *we will* should be more inclined
to do the molding. Maybe the unorganized documents should go into a
pre-review stage, but that seems unlikely to be successful, because the
review process is already encountering some problems.
If David publishes this short authors' guide, maybe it can be deemed
required reading. Then when a document that needs major help is posted
to the discuss list, the author can be directed to a reasonably short
resource to get started. At that time also, suggesting some general
points about the document that need to be worked on. I think it is
helpful for the author to know that they still have alot of work to do,
if that is the case. A harsh review is probably better than silence.
The author may decide that is more work than they want to do, but they
may also produce a document that they can be proud of, and take an
interest in even after it is published.
If there really are volunteers that want to take documents from mere
notes, to quality HOWTOs, they should be singled out by name. It
doesn't appear that most of us are willing to do that. Then when the
mere notes documents are posted to the list, the authors can be directed
to <name-of-willing-volunteer>.
>
> </notes>
--
Doug Jensen
