On Thu, 7 Aug 1997, Ralf S. Engelschall wrote:
>
> STATUS of the Apache Documentation Project (ADP)
> ================================================
>
> Goal of the project:
> --------------------
> (Feel free to fix me)
>
> Initial goals:
> 1. Create an Apache Handbook and an Apache FAQ.
> which contains most of the important material
> from apache/htdocs/ and apache-site.
I am a bit unclear of what, or more precisely who is the
Handbook targeted for: is it targeted for the users of apache (webadmins)
or is it targeted towards developers (new-httpd, outside module
developers) or someone else ?
There is a great need to separate the two, as writing the docs for
the developers is completely different from the ones for the users.
Furthermore, I disagree on you plan to port all the existing docs to the
new format. Allow me to babble for a few seconds: porting all the docs
to the new format would require an immmense effort and by the time it is
completed, almost all of it would be outdated, as 1.3 version will be most
likely released and 2.0 would be mostly incompatible with current design
(although i am note sure, i don't know if anyone is). Therefore, it would
be a good idea to start from scratch in the areas which are unlikely to
change by 2.0 timeframe, but we are still lacking now. For example, CGI
specs are unlikely to change in near years and Apache would still be
passing same variables to every CGI script (even though internal mechanism
would have changed), so complete description of how it works, what
variables are present, etc would unlikely to change and the effort would
not be wasted. I do realize there is some overlap, but I would like to
emphasize stable long-term docs first, before moving to the newer stuff.
If immeddiate (i.e. 1.3) documentation is required, then i would recommend
splitting into 2 groups and working side by side.
Ralf: if it is possible for you to setup a table of contents on some web
page, would really appreciate it, as people may want to take a look at it
and add to it, otherwise we are serializing the things-to-do, which is not
as efficient.
Stanley.
