apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ge...@everythingsucks.co.uk
Subject Re: Documentation
Date Sun, 01 Jan 2006 15:01:05 GMT
[Comments in line]

Quoting Paul Querna <chip@force-elite.com>:

> 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


Mime
View raw message