To: apache-docs@apache.org
Subject: Re: Apache Doc Project
References: <199811041611.RAA02584@cdc8g5.cdc.polimi.it>
From: Andrew Ford <andrew@icarus.demon.co.uk>
Date: 10 Nov 1998 15:30:18 +0000
In-Reply-To: stefano.gobbo@MAIL.BIBLIO.POLIMI.IT's message of "Wed,
 4 Nov 1998 17:10:00 +100"
Message-ID: <m3k913pnud.fsf@icarus.demon.co.uk>
Lines: 66
Sender: apache-docs-owner@apache.org
Precedence: bulk
Reply-To: apache-docs@apache.org

>>>>> "Stefano" == "Stefano Gobbo" <stefano.gobbo@MAIL.BIBLIO.POLIMI.IT> writes:

    >> >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.
    Stefano> I agree, but what I mean here is something like GETTING
    Stefano> STARTED, SITE PLANNING GUIDE or CONCEPTS. Whereas some
    Stefano> issues seems to go outside the track, I fear this could
    Stefano> be the only way to purge pearls like mod_rewrite in
    Stefano> no-tech people.

    >> Good point, and relatively easy to accomplish.  FrameMaker,
    >> HotMetal, Doc-to-Help - all do this kind of thing.
    Stefano> Scanning old apache-doc archives I noticed that someone
    Stefano> (in the core group) stated they would nont accept any
    Stefano> mean that couldn't be accessed via a dumb
    Stefano> terminal. Probabily, even more, there'll be the need to
    Stefano> layer the approach (i.e. low level tools for tech docs vs
    Stefano> GUI/Web approach for books)

I would suggest using SGML with the DOCBOOK DTD.  The Linux
documentation project is using it and it allows for conversion to
HTML, plain text and to print using TeX.  Other formats are also
achievable.


    >> >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.
    Stefano> Of course, everything which supposes even minimal
    Stefano> interference in the main track will be subject to the
    Stefano> core staff approval. OTOH some side effects will be
    Stefano> probable.

The Apache quick reference guide that I created used some perl scripts
to extract information from the source files to come up with the
original descriptions of the directives.  If information can be
extracted automatically from the source code then there is a higher
probability that it is going to remain accurate.  You could have a
hints database that added information where it was missing, with the
extraction script flagging where the hints provided information that
was found in the sources -- this would probably represent cases in
which developers have added information to the source and so the hints
had become redundant (or wrong).


Andrew
-- 
Andrew Ford,  Director       Ford & Mason Ltd           +44 1531 829900 (tel)
A.Ford@ford-mason.co.uk      South Wing, Compton House  +44 1531 829901 (fax)
http://www.ford-mason.co.uk  Compton Green, Redmarley   +44 385 258278 (mobile)
                             Gloucester, GL19 3JB, UK