Apache Doc Project

[Stefano Gobbo <st...@mail.biblio.polimi.it>]

In data 3 Nov 98, alle 15:20, Michele Petrovsky wrote:
> So, folks, what might we do for our first "Apache Documentation Group"
> project?  Some of the fellows at new-httpd suggested the following:
> 
>         * a "User's Guide" that would offer step-by-step, "how to
>           install and configure" instructions
>         * some simple, "canned" configurations, already zipped and
>           ready to download and install
Don't flame me, but what I have in mind is a far more drastic move toward an 
enterprise packaging of the jewel. Maybe i had to wait these posting 'till i had 
something more concrete, but as the bazaar theory teachs...

So, since the talk began, let's talk! 
I deeply believe that the first step we must get into is to plan the route we 
want to follow. Call it Project Guidelines. These are the topics IMHO we need 
to cover:

1. a set of book-style docs covering the various aspects of deploying a
   *web-based information system* with Apache. Some must be directly
    related to the product itself, while other should be more business oriented.
    For example, here is the place where to cover aspects as power
    deploying style - exploit the most from your web server. 

    Michele, I grabbed your Guide template and promise you to take a look at
    it ASAP.

2. engineerize the technical documentation, providing a mean by which 
    access it in a more dynamic and flexible fashion. Moreover, define a
    framework on which module developers should adhere for documenting
    their work. There is even the need of documentation affording the internal
    architecture and design of the Apache software (as suggested by
    Mohammed)

3. exploit at most the existing developer oriented docs, both by working on
    an API REFERENCE GUIDE and by planning a sort of API SURVIVAL 
    GUIDE. Consider that this need already lies somewhere in the 2.0 status
    guideline.

4. build a DocPortal as proposed by Kraaij, and evaluate the needs of writing
    some ad-hoc modules: what a best adv of a full featured doc portal built
    straight on the product we are documenting?

5. at this point you are surely asking: how push this sort of info to the
   community? papers, papers and papers. We'll eventually need to write
   some case study in the style of  "Apache Documentation Server
   Architecture and Implementation".

6. in which format/structure must we produce this bunch of data?
    this is a bit more complex than someone could expect, since IMO
    we must face this topic in a layered fashion: raw data format,
    end user format, dev oriented format, metadata, etc.

7. don't forget the target of it all! Query the Apache user base for which kind
   of document they wold feel comfortable with.

I'm the first in realizing that the challenge I pose here is VERY ambitious. 
But, at least for me, it's even stimulating.

Please, consider I'm currently in the process of making out a document itself 
from this, so be patient and give me as much as feedback you want.






----------------------------------------------------------------------------
Stefano Gobbo                         mailto:Stefano.Gobbo@biblio.polimi.it

IT Manager
Library Information System            Tel:    +39 02 2399 2292
Politecnico di Milano                 Fax:    +39 02 2399 2294
Italy                                 Web:    http://www.biblio.polimi.it