Re: [OT] OpenSource Documentation Fund

[Tom Fawcett <fawcett@mindspring.com>]

John <jcj@spiretech.com> wrote:
> my old computer (which used to run NT), put a new, cheap, hard drive in it
> and installed Corel Linux just to see what all the Linux hoopla was about.
> I found the documentation that came with it pretty useless. Were it not for
> newsgroups and friends helping me out, I would never have gotten the
> network or the modem working. At that, I bought the Idiot's Guide, but it
> didn't help a lot either.

Many authors are interested in feedback and would like to know whether (and
why) their documents aren't useful.  I welcome comments from intelligent
beginners, and especially from people who seem to have good writing
aesthetics and can explain where my document is lacking.  I take feedback
seriously though I don't make every change suggested.

> One thing that seems to be completely lacking, both in the LDP and
> currently published books, is a troubleshooting guide. For example, what if
> someone went through the newsgroups and compiled the most commonly asked
> questions ("The ppp daemon died unexpectedly -- what does that mean?") --
> and then did a step-by-step checklist for the user to go through. I sure
> wish I had been able to get my hands on something like that. Would have
> saved me a lot of frustration and a lot of my friends' time and effort.

IMO, each task-specific document should have a troubleshooting section for
the task.  The PPP-HOWTO should have one that covers the example you give.

> The problem I found was that I would post a question in a newsgroup and
> people would respond by posting an URL to a document in the LDP. I would
> dutifully go to the URL, but the text was incomprehensible to me.
> Everything was written in Geekspeak. The authors assumed too much knowledge
> on the part of the reader, thus failing to define terms before using them.

Since you have a background in writing but not in Linux, it might be useful
to collaborate with an author to improve an existing document.

Regards,
-Tom


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