At 11:13 AM 12/1/98 -0500, you wrote:
>In my experience the Apache docs are good once you get to know them, but
>they require a bit of getting used to.
Very true.
>We're in a difficult situation right
>now because we're all (I assume) fairly comfortable with the docs
>and the other resources available (ApacheWeek, for example).
> All of this time we've
>spent with Apache has probably made us blind to the problems
>a novice will face just looking at the docs for the first time.
That's been the message I've been getting
from people I've talked to.
>
>Maybe what we're talking about is a very general tutorial about Apache
>itself. How the server works, what modules are, what the components
>of CGI
>are and how they can work with Apache (mod_perl, etc.).
>What about putting this very general guide together so people who are just
starting to look at
>various web servers don't have to really struggle to get a grasp
>on what Apache is and does.
Once again, a very good point.
>
>As for the more in-depth documents (ie. mod_rewrite) those are the
>sorts of things that should be tackled as they are starting to be
>understood... that way, you get all the answers to your newbie
>questions, and have the docs written before you forget
>the niggling details.
>
This is where questions as to structure, presentation,
audience etc. start to crop up. Once there's a good
general in-English tutorial of the type you've described,
a case could be made that the existing docs are sufficient
for all other needs (e.g., sysadmins, programmers).
So, should apache-docs concentrate solely on:
* producing a tutorial
* broadening/facilitating access to the
existing docs (e.g., a document "portal"
as has been suggested; creating numerous
format versions such as PDF, SGML)
or do we need other levels/types of documentation?
And if the latter, what?
Michele
