[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [OT] OpenSource Documentation Fund
John <[email protected]> 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 [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]