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

[Paul Boddie]

On 18 Aug, 05:19, ru... at yahoo.com wrote:
>
> 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.

Well, "Annotatable Documentation" is an external link. All we can do
in such cases is to tidy such stuff up, mark it as invalid, or remove
it.

> Second try, DoumentationDiscussion: two very short paragraphs dated 2003.

Right. There are parts of the Wiki which were used actively in the
past but which have fallen into disrepair. Some pages lack focus -
they've been created according to "old school" Wiki conventions which
I regard as being somewhat obsolete (just creating new pages all over
the place to cover whatever happens to be in the writer's head at the
time) - and every now and again, I attempt to rationalise these pages
and focus their content.

> 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.)

It needs work, of course.

[...]

> 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.

Indeed. There's always the editorial bottleneck unless it's a total
free-for-all situation. I've remarked before about how user comments
don't necessarily add significantly to documentation, which is an
assertion that some people make, and there definitely does need to be
a process of integrating the best feedback into the main work. The
crucial difference between a Wiki and an annotation system is the
combination of the contribution and editorial aspects in a Wiki - you
edit the actual work, and people can decide whether it's a good edit
or not - in contrast to their separation in most annotation systems.
In some cases, strict annotation systems are probably better: the
GPLv3 annotation system was oriented towards discussion of the text,
and that's not so effectively done in a Wiki.

> 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.

Where there's a separation of annotation and editing, I worry about
the editorial bottleneck. I also worry about "handprint" edits more
generally, where people just want to leave their touch on the work
without actually contributing anything of substance.

> 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.

I'm happy to see tangential work rather than stuff which fills exactly
the same role as the current documentation. For example, the Python
module of the week articles (PyMOTW, [1]) are exactly the kind of
tangential work that could be encouraged, even though that is not so
much a collaborative work itself.

Paul

[1] http://www.doughellmann.com/PyMOTW/