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

[Antoine Pitrou]

Paul Boddie <paul <at> boddie.org.uk> writes:
> 
> A free-for-all isn't likely to be the best solution for more actively
> edited Python documentation, but Wiki solutions undeniably provide a
> superior "fast path" for edits by trusted users to be incorporated and
> published in accessible end-user documentation.

Agreed.

> I'm starting to believe
> that there's a certain snobbery about Wiki solutions which lead many
> people to develop all sorts of short-term, arcane solutions under the
> illusion that something super-special and customised is necessary and
> that they have to start virtually from scratch in order to cater to
> the ultra-special needs of the target audience; by the time they're
> done, no-one's interested any more, except to propose the next legacy
> system in the making.

Not sure why you think it's snobbery... There are certain tacit expectations
regarding the docs:
- that they are versioned with the source tree (because, often, changes in
documentation will be synchronized with changes in behaviour / functionality, 
because we must maintain documentation for several versions at once, because you
want to use the same kind of merging that is used between different branches)
- that they can be used offline, rebuilt in different formats, etc.
- that you don't need a Web server (even locally) to navigate through them
- that proposed changes are to be reviewed by maintainers (core developers)
before they get actually committed

I'm not sure of any existing wiki system which fits the bill. So, while I agree
that the current situation can present a high threshold for occasional doc-only
contributions, there doesn't seem to be a simple solution to improve things.