[prev in list] [next in list] [prev in thread] [next in thread] 

List:       apache-modperl
Subject:    Re: Thanks to Stas - a Q
From:       "Greg Cope" <gjjc () rubberplant ! freeserve ! co ! uk>
Date:       1999-07-29 19:53:34
[Download RAW message or body]


-:> OK, I have a 'however', and this is it:
:> The fact that Stas has to answer so many questions about "howto this"
:> and "howto that" says to me that the online docs are not well organized;
:> I've experienced this myself.
:
:That's true. I have 3 things to tell about it.
:
:1. Many times people who ask questions either don't know the guide and
:other docs exist at all, or do know but think it's not there. So the first
:things is to make sure that people will check out the available help
:before asking on the list, which is not always being done.


Many be make it more obvious on the web site (nice BIG letters)

:2. You are absolutely correct about bad organization. While I'm writing
:and maintaining the guide, many times I have a problem to find the info
:myself. I know it's there but it takes me a while to find it. The problem
:is that no one suggests how to make things better. If you read the guide
:and think that some interesting info is hidden and is not accessable from
:the Table of Contents - you should tell me, if you wouldn't tell me I
:don't know what you and other are missing.
:
:3. Submissions. I'm working hard to try to keep up with the traffic on the
:list to filter all the interesting questions and answers to add these to
:the guide. Certainly I'm far from being an expert and I wouldn't add items
:I don't understand myself. So if you think you've been hit by some general
:problem and you've solved it, or was helped to, write up a few lines that
:explain the problem and the solution and send it to me. If you don't do
:it, chances that it will show up in the guide are much smaller.
:
:We have also started the modperl garden project modperl.sourcegarden.org
:that one of its goals is to improve the documentation thru the series of
:articles and tutorials. You are welcome to visit the site, subscribe to
:the list and suggest your help.
:
:> My premise is that for propositions with a steep learning curve ( of
:> which mod_perl is one -- people who want to use it effectively are
:> forced to learn the low-down on server request cycles) it is useful to
:> produce 'cookbooks'.  Most people (including me) learn best by example.
:> The more examples the better. Examples allow users to get their stuff
:> working and enthuse them to learn more (the previously-mentioned server
:> internals).
:
:The same as above, gimme a hand by writing up the examples for the
:material in the guide and they will show up there.
:
:Regarding the cookbook, if everything goes as expected I want to turn the
:guide into a cookbook to be published sometime in the future. Suggestions
:and ideas are welcome.


Excellent idea.

I have been trying to Learn perl / mod_perl and finding examples is a
problem - I especially like the Orielly Perl Cookbook - something similar
would be excellent.

Perhaps a link or section on the web site pointing people to code examples
would be good - some parts of the web site are excellent (the guide and the
optimisation bits) but I feel that an idiots guide to what is going on would
help newbies ?

regards

Greg Cope

[prev in list] [next in list] [prev in thread] [next in thread]