Subject:
Re: [discuss] Proposed: Author-Mini-Howto (full text)
From:
"Amit Choudhary" ####@####.####
Date:
31 May 2008 20:06:56 +0100
Message-Id: <123917630805311214s7a4a0931sc78a6037d47e2b3d@mail.gmail.com>
This might be a little off topic but I feel that we should allow authors to
write a HOWTO in text format - just like RFCs and internet drafts. When
someone wants to write a RFC he can do so immediately, and the world gets
some valuable invention like OSPF, BGP, etc. There are so many RFCs and so
many internet drafts and people have built billion dollar business based on
them, so we should not think that knowledge in a text based format is not
good knowledge and that people cannot understand it.
The questions that come to my mind are:
1. Do we want to unlock the knowledge or unlock it in a particular way?
2. Is forcing people to learn linuxdoc, etc. forcing them to not release
their knowledge?
3. Can you not understand something that is written in a text file?
4. Is this project suffering because of the bureaucracy of presenting the
knowledge in one particluar way for which the author has to invest time in
learning it?
We are interested in unlocking the knowledge that people have, we should be
just doing that. The text document can undergo rigorous review by members of
this list. I have written the system call howto and that was translated by
someone else. However, I did not see any difference in people implementing
the text version of it or the official version of it. I have to update it
but since I have to invest time in learning it, it is kept on being
postponed.
My 2 cents. If you do not like this approach then please ignore this
message. I am writing this mail because I feel that the knowledge is not
getting unlocked because of the restriction of having it in a particular
form.
-Amit
On Fri, May 30, 2008 at 11:37 PM, David Lawyer ####@####.#### wrote:
> 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<http://www.nyx.net/%7Esgjoen/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>
>
> ______________________
> http://lists.tldp.org/
>
>
