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

[rurpy at yahoo.com]

On Aug 11, 4:08 pm, Paul Boddie <p... at boddie.org.uk> wrote:
> On 11 Aug, 23:50, ru... at yahoo.com wrote:
> > However, were the Python docs site to provide a wiki, along
> > with a mechanism to migrate suggestions developed on the wiki
> > into the docs, it might well be a viable (and easier because of
> > the wysiwyg effect) way of improving the docs.  As other have
> > pointed out, Postgresql, PHP, and Haskell have done so.
> > Now maybe there are good reasons not to do that.  But your hand-
> > waving is not one of them.
>[...]
> I can see benefits to just starting from scratch. Perhaps the
> licensing should be more explicit than the existing material on the
> Wiki so that the documentation produced could be freely distributed
> without uncertainty, but the outcome would hopefully be something that
> stands on its own as an alternative or a replacement to the
> conventional documentation.

A couple years ago I actually did give a half-assed try to rewriting
the doc.  I got the doc source downloaded and buildable with the
intent
of rewriting in bits and pieces as I had occasion to use (and find
problems with) various parts.  Not knowing latex, I stupidly got side-
tracked trying to convert it to docbook which I was more interested
in.
After I gave up on that and went back to latex, I found merging
changes
from Python into my source (a little of which was heavily modified by
this time) to be very time consuming.  And eventually the Python side
was changed to REST putting an end to my effort which by that time
were already pretty minimal.  I concluded that the rewrite I was
trying
to do was comparable to writing a Python book, and too ambitious for
one person working on it <5 hrs/week.

And of course I am not any better writer (probably worse) than the
average Python programmer.  Which is the problem with using a wiki --
unless good writers contribute, I see no reason to expect much
better results than already exist.  But maybe I am too pessimistic...