[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Slashdot reply (draft 0.2)
On Fri, 11 Feb 2000, Guylhem Aznar wrote:
> <<
> Thanks a lot to slashdot readers for the comments they submitted.
>
> Our announcement may have seemed "empty" but you provided us many
..."empty", but you provided us with lots of good feedback regarding...
> feedback regarding the LDP in general, and that will help us improving
...help us in 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.
...on the first page.
> Please check "non English" where you should find a link to your local
> LDP with translated documents.
We can use softlinks to build this heirarchy from the heirarchy I
described in my previous email.
> - provide security bulletins
>
> I'm sorry but this is not in the current goals of the LDP.
...is not one of the current...
> 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
Can we make these available through a LinuxDoc.org URL?
> another output, just like the html and ps versions.
>
> Since 2 persons also asked a pdf output I'm also working on that.
...2 people also asked for a pdf...
>
> - 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.
...will be accepted. We are...
> You can already submit your DocBook only document which will be put in
> the DOCBOOK section. (a new major section, like FAQs and HOWTOs)
DocBook should be a presentation format dir under HOWTO or FAQ or GUIDE as
appropriate.
> - "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
I agree with Greg Leblanc that this is totally bassackwards.
The formats are secondary to HOWTO, FAQ and GUIDE.
However there is definitely a problem for accepting documentation from
people who don't submit in SGML for whatever reason. I think the main list
should list the subjects, then list the available formats and languages.
3Dfx HOWTO by Bernd Kreimeier <bk@gamers.org>. How to use 3Dfx...
Available as html (en, de, pt-BR), LinuxDoc, ps, pdf, text
Or better yet, the 3Dfx HOWTO points to the LDP 3Dfx HOWTO home page,
which then lists the various presentation format/language combos
available.
Another option is:
3Dfx HOWTO by Bernd Kreimeier <bk@gamers.org>. How to use 3Dfx...
Also available as LinuxDoc, ps, pdf
with the "3Dfx HOWTO" at the front remaining as it now is, e.g. a link to
the first html page of the HOWTO.
Or we could have a warning:
some-no-sgml-only HOWTO by Fred von Jupiter <fred@jupiter.planet>. How...
This HOWTO is only available in the following format(s): text, ps, pdf
Then there's either no link from the title or it follows to the next level
of the heirarchy that we would decide, e.g. html, text, pdf, ps, info,
whatever.
> Then please a license compatible with our requirements (GNU Free
Please us a licence compatable...
> 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
...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
proofread, I believe.
> 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).
I'd prefer a different wording:
However, there are far too many docs submitted to ldp-submit for our small
team to adequately proofread each document. If you would like to help us
please subscribe...
Maybe:
If you would like to join our team and help us...
> - XXXX and YYYY HOWTOs are outdated/unmaintained
>
> Please update the document if the license allows modifications.
Please update the document and submit the new version to the LDP if the
license...
> 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.
Should that be "non-free"?
> - license problem, GNU/Linux... FIXED
>
> We have a manifesto and a license guide on the first page ; both are
> currently being revised.
...first page. Both are...
> 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 this can be better written as:
Sorry for the long reply. We would like to help the Linux community as
much as we can, but writing documentation is not seen as being as sexy as
writing software. Documentation or authors often don't get as much credit.
(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")
I think my syntax is a bit better, e.g. period after apps. The ('s aren't
really necessary, but they aren't bad either.
In any case no space before the : and a period at the end of the quoted
sentence.
> 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.
I like Dan Scott's rewrite of this paragraph:
"We do need more authors. Unfortunately, not everyone can be a good
author. It requires a combination of writing skills, technical knowledge,
and the willingness to accept criticism that improves your final product.
Thank you all for your responses--we hope that you continue to let us know
your opinions on the LDP."
It might be nice to add something about just using the LDP and submitting
bg reports and suggestions are also good ways to participate in the LDP.
The two suggested paragraph rewrites might not capture the spirit of what
you were trying to express. Sorry if I've misunderstood the intended angle
of what you wrote.
ciao,
der.hans
--
# +++++++++++=================================+++++++++++ #
# der.hans@LuftHans.com #
# http://home.pages.de/~lufthans/ #
# Science is magic explained. - der.hans #
# ===========+++++++++++++++++++++++++++++++++=========== #
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org