httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michele Petrovsky <petro...@voicenet.com>
Subject Re: Apache Doc Project
Date Wed, 04 Nov 1998 15:22:21 GMT
At 12:28 PM 11/4/98 +100, you wrote:

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

Far from flaming - I think everything you're suggesting here is right on.

>Call it Project Guidelines.
>
>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.

It was in an effort to establish this sort of orientation that I came up
with the outline I forwarded.  I doubt too many business types will
understand or even care about phrasing like "module mod_log_referrer" or
"log file format".  Most businesspeople just want to know that something
works, not how and why it works.  And they want to know in terns they
understand what it can do for them.

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

Good point, and relatively easy to accomplish.  FrameMaker, HotMetal, 
Doc-to-Help - all do this kind of thing.

>Moreover, define a
>    framework on which module developers should adhere for documenting
>    their work.

This might be outside our area of responsibility.  Seems to me the members of
the core group of developers would have to contribute to/agree to this.

 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.

You must be psychic.  This is another suggestion that several of the
core group made to me when I originally aproached them re: helping out.

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

Once again, I agree.  I'd suggest case studies of existing Apache 
implementations of a number of degrees of sophistication, as well as 
studies/popularizations of our efforts. 

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

These aren't the only decisions of this kind.  We'll also need to
provide for a variety of means of delivery.

>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 can get started with this one.  I have associations with several
environments which run Apache - an engineering firm I used to do
documentation work for, and the college at which I currently teach.
I'll start asking questions to the system and network administrators
at both those sites.

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

Ambitious and stimulating indeed!  I think the possibility
of aiding and influencing the acceptance of something like Apache
is exciting and worthwhile.

Take care.

Michele


Mime
View raw message