The ones on python.org seem to function reasonably well. I accept that
they could be more aggressively edited, but this isn't done because
there's a compromise between letting people contribute and keeping
things moderately coherent, with the former being favoured. For other
purposes, it would be quite acceptable to favour editorial control.
Yes, I agree. I should have mentioned this as an exception
in my "wikis suck" diatribe. Although it far better than
most wiki's I've seen, it is still pretty easy to find signs
of typical wiki-ness. On the Documentation page my first
click was on AnnotableDocumentation: 404. Second try,
DoumentationDiscussion: two very short paragraphs dated 2003.
After that I found some useful (in general though not what I
was looking for) information but not a good first impression.
(Well not exactly first, in fairness I have used other wiki
sections such as the Templating page and found them very
useful.)
I won't argue that providing infrastructure solves a problem - that's
precisely the kind of thing I was criticising when I noted that some
people will readily criticise the choice of tools to do a job instead
of focusing on the job that has to be done - and you need people who
are reasonably competent editors, but Wiki solutions remove a lot of
technical barriers. I'm not arguing for the flavour of Wiki which
implies unfettered, anonymous access from everyone on the Internet,
either: the kind of Wiki that detractors portray all Wiki solutions as
being in order to further their super-special "it has to fit like a
glove or it's totally unusable" software agenda. It's quite possible
to have people with somewhat more privileges than others in order to
keep the peace, and they don't all need to have an entrenched
editorial interest: on the current python.org Wiki sites, most of the
administrators don't have an active interest in most of the content,
but they are able to exercise control when it's clear that some
contributors aren't particularly interested in actually improving the
content.
As well as having an active community effort around the existing
python.org Wiki sites, there are also people who are interested in
improving these offerings. What worries me is that despite such
activity and such interest, many people will continue to lament the
lack of vitality (or whatever other metric) of the general python.org
offering, whilst retaining a blind spot for the obvious contribution
that the Wikis can make to such improvement efforts. I encourage
people to use wiki.python.org a lot more, should they be looking to
improve the wealth of information provided by the community.
Again, I agree with all of that. But my main interest is
in improving the standard docs that are distributed with
Python and I question a wiki's role in that.
I took a look at the PHP docs last night which seem
pretty well done. The User Comments looked rather as I
expected, there was useful info but most did not contain
documentation quality writing. So if they are used as
a source for improving the docs, there clearly must be a
pretty large amount of editorial effort required, although
much of it is probably just filtering out comments that
don't provide any information appropriate for inclusion
in the docs. They list 38 names under "User Note Maintainers"
(
http://www.php.net/manual/en/preface.php)
Unfortunately I couldn't find a description of what these
people actually do. I don't know how much work was involved
in removing the comments that are no longer there.
Again, I don't mean to sound like I am dissing the idea
of annotatable docs -- I think it is a good idea and will
provide useful supplementary information.
But I continue to question whether this will result in
improvements in the docs themselves (which is my main
interest) unless:
1. The purpose of the wiki is clearly "marketed" as
soliciting suggestions, rewrites, etc destined ultimately
for inclusion in the docs.
2. There is a dedicated core of doc-competent volunteers
focused on extracting, condensing and editing the user
comments and getting them into the docs, either directly
(if the volunteers are committers -- unlikely) or through
the existing tracker system. And this still fails to
address the problems with the docs that aren't amenable
to fixing via the tracker system. At least two of those
problems are:
1. Difficultly in making large organizational changes.
2. Prevalent opinion among doc approvers that the current
excessively terse style is desirerable.
