Slashdot reply (draft 0.2)

[Guylhem Aznar <guylhem@metalab.unc.edu>]

<<
Thanks a lot to slashdot readers for the comments they submitted.

Our announcement may have seemed "empty" but you provided us many
feedback regarding the LDP in general, and that will help us improving
our quality.

While reading the comments, I took a paper and wrote down the different
problems people had.

Some will not be solved immediately, some are now solved :

  - web site design : FIXED

Each of your comments were precious to help us improve its appearance
and ease of use.

You can try the new version.

  - provide direct access to important links : FIXED

We now have big links for each of the major document types (HOWTOs,
FAQs...) in the first page.

Please check "non English" where you should find a link to your local
LDP with translated documents.

  - provide security bulletins 

I'm sorry but this is not in the current goals of the LDP.
However, if there is a strong demand, we could start a brand new
section.

  - link to RFC archives

I'm sorry again but this is not Linux specific.

  - provide DocBook and PDF documents : FIXED

I converted each of the LinuxDoc HOWTOs and mini HOWTOs to DocBook and
uploaded them 2 days after the Slashdot article ; they are now available
on ftp://metalab.unc.edu/pub/linux/docs/HOWTO/other-formats/docbook as
another output, just like the html and ps versions.

Since 2 persons also asked a pdf output I'm also working on that.

  - move to DocBook because LinuxDoc sucks
  - stick to LinuxDoc because DocBook sucks

The HOWTOs are now provided in both LinuxDoc and DocBook; however for
the moment we can only accept LinuxDoc source for the HOWTOs.

In the next weeks both DocBook and LinuxDoc sgml source will be
accepted, we are currently testing DocBook output formats.

You can already submit your DocBook only document which will be put in
the DOCBOOK section. (a new major section, like FAQs and HOWTOs)

  - "tables don't scale to window size and resolution and 10 pt font
    size is hardcoded

Our webmasters are working on these problems.

  - How can I submit my work to the LDP?

4 possibilities : 
a. you can write in LinuxDoc : call your document an HOWTO
b. you can write in DocBook : call your document a DOCBOOK :-)
c. you are a master of TeX/LaTeX, pdf or any specific format : call your
   document a GUIDE
d. you only know ascii and html : call your document a FAQ

Then please a license compatible with our requirements (GNU Free
Documentation License is IMHO the best choice but feel free to take any
other license) and mail your document to ldp-submit@lists.linuxdoc.org

If your LinuxDoc or DocBook source contains errors, I'm sorry but we
won't process the document, please test it first

  - You should check the documents : FIXED

We already do!

Since november, a peer reviewer team is trying to proof read each
submitted document.

However, there are far too many docs submitted to ldp-submit.
We can not proof read each document ; if you feel like helping us please
subscribe to ldp-submit (mail ldp-submit-request@lists.linuxdoc.org).

  - XXXX and YYYY HOWTOs are outdated/unmaintained

Please update the document if the license allows modifications.
We will be happy to include your new version (News HOWTO and SCSI HOWTO
are especially old!).

  - I just found ZZZZ HOWTO which is not part of the LDP yet

Then please contact the author and ask him to send his document to
ldp-submit@lists.linuxdoc.org

Chances are we will include it, unless it contains errors, has a non
free license, or duplicates an existing document.

  - license problem, GNU/Linux... FIXED

We have a manifesto and a license guide on the first page ; both are
currently being revised.

We will not impose any license but rather have some criteria and
requirements (free redistribution for ex.)

And if you don't like "LDP", just remember netscape/mozilla : it's
written LDP but it reads GNU Linux Documentation Project.

				  ***

Sorry for this long reply, we would like to help the community the best
we can but writing documentation is not as sexy as writing software, and
documentation or authors themselves are poorly considered (quoting a
slashdotter: "Honestly, how many users want to read documentation? How
many of them see a fat manual and feel happy?")

I think programmers should try to document their own apps (quoting a
slashdotter again : "If I can't clearly and concisely write what I'm
doing then my algorithm just isn't very good")

And we need more authors, but anybody can't be an author, it requires
skills, knowledge and a bit of disinterest for when people criticize your
HOWTO they didn't even read.

PGP signature