On Sunday 01 January 2006 15:01, [EMAIL PROTECTED] 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
