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