httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From (Ralf S. Engelschall)
Subject Re: [STATUS] ADP (Thu 7-Aug-1997 23:27 MET DST)
Date Fri, 08 Aug 1997 08:44:27 GMT

In article <Pine.GSO.3.95q.970807221231.12443A-100000@csa> you wrote:

> 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 ?

Yes, correct. We need a Handbook for the developers and adcanced webmasters
and a user manual for the avarage webmaster and normal user.

>   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.

Exactly. Good point.

> 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.

Yes, but I don't want to convert the existing docs manually.  I want to write
perl scripts who do 95% of the conversion and the ADP team also has to enhance
it in the future for 1.3 and 2.0. Starting with not-changing topics is ok,
too.  We should do both. Writing from scratch is fine for not-changing topics
and the remaining stuff is just automatically imported from the existing

> If immeddiate (i.e. 1.3) documentation is required, then i would recommend
> splitting into 2 groups and working side by side.  

No, it's not required, 1.3 is happy to be released with the current bunch of
HTML pages. That's ok.

> 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.

I'll do this but first we should decide about the tools, because I hate doing
things twice just because we want a different language/tool.  So please first
decide about the tool, then we discuss the TOC and then we discuss style
guides and split the work. Is this order ok?

                                       Ralf S. Engelschall

View raw message