apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nick Kew <n...@webthing.com>
Subject Re: Documentation
Date Sun, 01 Jan 2006 16:18:26 GMT
On Sunday 01 January 2006 15:01, gerry@everythingsucks.co.uk wrote:

> Total completeness and accuracy in software documentation is very hard
> to achieve but especially in rapidly evolving projects such as APR.  So
> it becomes a question of acceptability and hence means the quality of
> the documentation is subjective.

That seems to be an argument for what has happened in practice:
the API documentation in the header files and Doxygen is complemented
by third-party sources (apachetutor and ariel-networks).

> In my opinion community-driven documentation is one good way of
> delivering fast results.  What the PHP Group have done is produce a set
> of interactive documentation on which their user-base can offer
> feedback, corrections and examples - and where other users can find
> them without digging around in bugzilla or mail lists.

FWIW, apachetutor is designed to be a halfway-house between author-
driven and community-driven documentation.  The software (which is
lightweight and comprises entirely Apache modules) supports both
multiple authorised authors and anonymous community feedback.
If you're interested in contributing there, I can set up an account for you.

> It is also important that quality-gates are put in place for any user
> contributions to ensure that only those which are accurate and
> generally use-full are actually published.

We manage that in the context of the httpd docs by restricting access
to trusted people (committers).  That's probably the best we can reasonably
expect when noone is being paid to review documentation.

> > (1) Okay, so its not written in stone anywhere, but I think there
> > would be major resistance to running PHP on the main apache.org
> > webserver(s).  Maybe we will have more options once FastCGI support
> > is in mod_proxy... but not right now.
> [GC] Absolutely fair, though in my defence PHP+MySQL was given as an
> example.

Should I throw mod_annot (apachetutor) into the pot at this point?
It's a much lighter-weight solution than PHP+MySQL:-)

Nick Kew

View raw message