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

[rurpy at yahoo.com]

On 08/12/2009 12:27 PM, Raymond Hettinger wrote:
> On Aug 12, 3:32 am, Paul Boddie<p... at boddie.org.uk>  wrote:
>> Maybe the problem is that although everyone welcomes contributions and
>> changes (or says that they do), the mechanisms remain largely beyond
>> criticism.
>
> FWIW, I support the idea the regular docs incorporating links to
> freely editable wiki pages.  That will at least make it easier for
> people to make changes or add notes.
>
> That being said, I would like to add a few thoughts about the
> current process.   ISTM that important corrections (when the
> docs are clearly in error) tend to get made right away.  What
> is more interesting are the doc requests that get rejected
> and why:

[...snip interesting categorization of "bad" doc enhancement
suggestions...]

> In short, most doc requests that get rejected are requests that didn't
> actually improve the documentation.
>
> I do support links from the regular docs to an external wiki but the
> main docs should continue to go through the regular process using the
> tracker.

What is the purpose of such a wiki?

1. To provide hopefully useful adjunct information for each
doc page?

2. To provide a source of input for improving the next version
of the docs?

In general I have a low opinion of wikis.  Nearly all the ones
I've seen are trash heaps of out-dated and wrong information,
atrocious writing, and comments that look like the middle of
some arcane usenet thread.  They lack organization making it
very difficult to find the needles of good information in the
haystack of junk.  The only one that seems to work is Wikipedia
and it "works" because it has a very heavy-weight process
controlling contributions.  (And even then, my biggest complaint
with Wikipedia is the poor writing quality in a lot of articles.)

I'm not trying to be negative, only pointing out that to serve
either of the goals I asked about above, a wiki will probably
require a considerable management effort that should be faced
up front.  To simply set up a wiki and "wait for it to
self-organize" (as I here read once) is a pipe-dream.

How will it be managed?  Anything written stays?  If not what
standards are used to remove junk entries?  Wrong entries?
Questionable entries?  Who will do this?  Will they act based
on their own judgment or some documented formal standards?
What happens to comments when a new doc version is released?
What happens when entries become obsolete?  What happens when
comments are disputed?

If the goal is (2) what kind of wiki contributions are being
solicited ("I don't understand what this sentence means"? a
complete rewrite of a section?) and how is that communicated?
Who will take a long string of wiki comments constituting a
discussion and condense them into something that can be
submitted as a doc patch?  (This I suspect is where the
work is, where someone with good writing skills is needed.)
Will this process be sufficient to raise the quality of the
docs significantly, or are other steps also needed such as
an attitude shift in what the core committers consider
acceptable?

If the goal is (1) above, it could potentially have a
deleterious effect on the docs in that it will be easier to
respond to requests to expand some description with, "there's
no need since that is covered in (or belongs in) the wiki
comments".

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.