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

[Paul Boddie]

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 think you make some good points, although I don't have time to
respond to all of them. Certainly, the documentation situation with
Python is not ideal; otherwise, people would not be complaining about
it so frequently.

I recommend going to the existing Wiki and looking at what there is
already:

http://wiki.python.org/moin/Documentation
http://wiki.python.org/moin/CategoryDocumentation

Sadly, I don't think you'll find much to work with, apart from the
occasional attempt to make an annotated version of the existing
documentation:

http://wiki.python.org/moin/PythonLibraryReference

So my next recommendation is to either use the existing Wiki
infrastructure or to ask for a separate Wiki for the purpose of
reworking the documentation. You could either take the existing
documentation, which I believe is now restructured text, and just drop
that into the Wiki with the appropriate format directives (for later
reworking in Wiki format, perhaps), or you could start afresh and
tackle some of the more serious issues head on.

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.

Paul