Social problems of Python doc [was Re: Python docs disappointing]

[rurpy at yahoo.com]

On 08/13/2009 08:46 AM, Paul Boddie wrote:
> On 13 Aug, 16:05, ru... at yahoo.com wrote:
>> All the above not withstanding, I too think a wiki is worth
>> trying.  But without doing a lot more than just "setting up
>> a wiki", I sadly believe even a python.org supported wiki
>> is doomed to failure.
>
> 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.