[Comments in line]
Quoting Paul Querna <[EMAIL PROTECTED]>:
The web host must be easily moved between servers. Our current
servers do not run a database for any TLP site.
The web host cannot run anything besides CGI. We only use a CGI for
the download page. I don't think we want to expand the use of CGI,
for the sake of the load average of minotaur and ajax.
Our website should be purely static files. This is currently a
requirement(1) for almost all the TLPs and their websites.
[GC] These are fair, though rather preclusive, points. I'd rather not
enter discussion of what the environmental constraints are at the
moment but instead to explore the Documentation problem further.
I think better documentation is a good thing. I don't want to stand
in the way of that. I am not sure I like the PHP method of allowing
comments. I believe documentation should be authoritative, not
'maybe this will work, but try this other way someone mentioned in
the comments'.
[GC] I belive that, in APR, the only authoritative documentation (i.e.
official, complete and accurate) is the source. This problem is,
of-course, not unique to APR.
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.
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.
If, for example, the doxygen API documents and any user-feedback are
treated as two seperate islands then I think we would end up with a
situation like 'maybe this will work, but try this other way someone
mentioned in the comments'. However this is not how it should work,
they should be complementary. It is important that the user-comments
influence the offical documentation (when appropriate).
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.
In my view this is the, now classic, open-source positive feedback
cycle. Better documentation means wider take-up, wider take-up means
more eyeballs, more eyeballs means more APR contributors both to code
and 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. Another example would be doing it all offline and publishing
periodic updates. User comments would simply be written to a text-file
and dealt with later. If/when the time comes that we implement
something like this then we can find an appropriate solution to deal
with these concerns.
Regards
Gerry Calderhead
