Doc suggestions (was: Why "class exceptions" are not deprecated?)

[Paul Boddie]

rurpy at yahoo.com wrote:
> Ed Singleton wrote:
> >
> > Ideas can come from anyone and they do come from anyone all the time,
> > and as such they are fairly worthless unless acted upon.
>
> That is pretty obvious.  The question is about who does
> the acting.  Your position seems to be that
> only those that act have a right to present ideas.  This
> is bogus for a whole bunch of reasons:

At this point, I have to say that this post reveals a pretty good
insight into the nature of community dynamics.

> - It is exceptional case when people go off and do something
>   by themselves and produce good results.  The power of
>   free software lies in its collaborative nature.

Indeed. Which is why it can be puzzling sometimes to see certain
communities and movements put all their money on one horse, to use a
common analogy. People should feel encouraged to do offbeat or
tangential stuff, especially if it costs the other people nothing more
than an act of encouragement.

> - Many changes are too big or pervasive, and need
>   cooperation from many people (or at least agreement.)
> - Even small changes often need help from others
>   (sometimes just information)
> - People can have a good idea, even if they are not capable
>   of implementing it.

And consider a combination of these factors: there are several
different resources for proposing amendments to the Python
documentation; to make a standard replacement for the documentation,
you need consensus; to make a better replacement, you either need
people to use your resource to propose improvements, or you need to be
able to collaborate with all the other resources/mechanisms, and thus
you need standardisation. No-one has all the technical, social and
political answers, nor should they be asked to come up with them all.

Having people proposing changes to the documentation and having tools
available to make such changes convenient both solve important issues,
but various social and political issues remain. If we ignore these
potentially unsolved issues, though, noting that Fredrik and others
have provided technical solutions, it'd probably be for the best if
those people perceived to be complaining were just encouraged to use
such solutions rather than being made to feel stupid because they don't
have the technical abilities to solve that one aspect of the wider
problem.

> - This is particularly true in documentation and ui where
>   the lowly user is, in many respects, the expert.
> - Even if an idea is not good, it can start someone else
>   thinking and their idea may be good.

Indeed. People who don't feel able to contribute to one part of a
solution shouldn't be discouraged from contributing where they can.
Perhaps it has been difficult to field documentation updates within the
current workflow, and perhaps it is more productive for the maintainers
to not encourage certain levels or kinds of suggestions or improvements
since they would end up with a lot of editing and administrative work,
but the technical impediments are not the fault of those willing to
contribute - if people lose sight of that, then...

> - Without outside ideas and critisism the core
>   development group can become "inbred" and loose touch
>   with the user community.

Well, there was the "smug" label brought up some time ago. I'd argue
that certain parts of the community could subsequently be labelled as
"rattled" due to certain arguable trends in technology adoption, and
perhaps the python.org redesign brought all this to the fore. And on
that subject, perhaps I'd better get back to looking at that particular
set of tools...

Paul