httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@engelschall.com (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
stuff.

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

Greetings,
                                       Ralf S. Engelschall
                                       rse@engelschall.com
                                       www.engelschall.com

Mime
View raw message