RE: Slashdot reply (draft 0.1)

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

> -----Original Message-----
> From: Guylhem Aznar [mailto:guylhem@metalab.unc.edu]
> Sent: Thursday, February 10, 2000 3:17 PM
> To: ldp-discuss@lists.linuxdoc.org
> Subject: Slashdot reply (draft 0.1)
> 
> 
> Hi,
> 
> Here's the message I would like to post after the slashdot announce.
> It provide us many feedback, which is listed underneath.
> 
> I think we should respond to the questions raised, I will post the
> following messages after comments & fixes (it's the 1st draft, freshly
> typed)
> 
[snip]
> 
>   - 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

<flame>This is really stupid.  I'm sure there's a logic behind this, but I
can't grasp what it is.  I understand why these were put in place, but not
why they're still in use.  We should abolish silly distinctions to allow
authors to more easily submit documents, especially since we're accepting
DocBook.  Hugo van der Wahls (I think I spelled that right) has made some
RPMs of the new versions of SGMLTools, so at least some people can do the
translation from DocBook to other formats.  Calling your document a FAQ
because you don't know any breed of SGML other than HTML is silly.  If we're
going to use the terms "FAQ", "HOWTO", "GUIDE", and whatever else, it should
be because the document logically is a FAQ, because it's a series of
questions, or a HOWTO, because it tells HOW TO do something.  If we're going
to classify documents by their format, let's just DO IT, and make categories
based on format.  But the best thing for users is to classify documents by
structure/content, and keep sections like HOWTO, FAQ, etc.  If necessary, we
could break sections down something similar to:

LDP/
LDP/FAQ/
LDP/HOWTO/ (put the actual plain text HOWTO documents here)
LDP/HOWTO/DocBook/ (put the DocBook source here)
LDP/HOWTO/LinuxDoc/ (put the LinuxDoc source here)
LDP/HOWTO/pdf/ (put pdf output here)
LDP/HOWTO/ps/ (put PS output here)
LDP/HOWTO/tex/ (put tex output here)
LDP/HOWTO/html/ (put html output here)
LDP/HOWTO/stuff I missed/ (put the stuff I missed here)
LDP/GUIDE/
...

And so on, for each type of document that's available.  For the markup of
documents, we should (for now) request that they be submitted in LinuxDoc,
with no errors (validating is easy).  Second choice should be DocBook, then
HTML, then either plain text or LaTeX or Tex.  We should not accept source
in pdf, or ps, or any of the ones that I've not mentioned here.  This
structure would allow us to accept just about any document anybody writes
about/for Linux.  Depending on how opaque TeX and LaTeX are, perhaps we
should not accept those either?  If we accept documents in any format other
than SGML (either DTD), we should encourage the authors to re-write those
documents in SGML.  Perhaps when these documents arrive, we can get a
volunteer to "translate" one section/chapter of the document to SGML and
send it to the author so that they have a good idea what it should look
like.  For BIG documents, like guides and things of that nature, we should
be a little more pushy about SGML, since management of big documents is much
harder in any other format.  I didn't mean to make that seem to be directed
at any individual, so please don't take it too hard.  Anyway, someplace in
there I ended that "flame" so I'll just close it here </flame>

> 
> 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

This should have a pointer to the manifesto so that they know what our
requirements are.

>   - 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.

This doesn't sound too good, it implies that we don't want this many
documents submitted.  We want MORE documents submitted, not less, right?

> 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).

If we really want this to work better, we should break things up a bit, or
change the guidelines for submitting.  People should contact someone from
the LDP BEFORE starting a project (I know, this is in the guidelines, but
maybe we should make it a bigger deal).  Once they're written a document, we
need to have people from the community in general read over it and review it
for content and some grammar/spelling.  Perhaps we should add another list,
the LDP-editors@lists.linuxdoc.org, as a place to submit documents for
grammar/style/markup editing, and the LDP-submit list should become an
automated submission mechanism.  

> 
>   - 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'm not sure that we should be singling (sp?) out any particular HOWTOs, but
perhaps pointing them to the page ordered by date that Greg F has created.  

> 
>   - 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?")

Ooh, me me me!!!  Maybe we should ask /.ers to help make documentation
writing "sexier" (I really don't believe that it's going to get me any
dates, but what the heck) by helping out with the LDP, either by sending
comments and suggestions on the HOWTOs that they use, or some other method
(ALL linux users use HOWTOs, I've been at this a long time and haven't
learned everything yet)

> 
> 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'm not sure that this is a good policy to take.  There are some programmers
who perhaps aren't very good at writing, but might be able to hack the
nicest, most efficient code you've ever seen.  I'd have to say that /.er's
quote isn't appropraite for this follow-up, nor is this statement.

> 
> 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 the re-write that somebody proposed much better than this paragraph,
it makes it sound like you shouldn't care if somebody bashes your HOWTO.
YOU SHOULD CARE, and you should try to discuss the suggestions/comments that
they made in order to improve your HOWTO.  Well, it's tomorrow already, and
I've got to be out of the house by 6:30 tomorrow, so I'll have to get some
sleep.  Again, not wanting to come off as an a$$ &%*@, I'll appologize to
everybody I've offended, and especially to Guy, since he's doing a great
job.
	Grg


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org