Doc suggestions

[Ed Singleton]

On 4 Apr 2006 15:18:27 -0700, rurpy at yahoo.com <rurpy at yahoo.com> wrote:
> <rurpy at yahoo.com> wrote in message
> > Here is a 30000' view.  I posted about a clear
> > (admittedly very minor) doc problem 8 days ago.
> > Since then there have been 30+ postings in this
> > thread.  Insults and bad feelings have flown.
> > Two people setup wikis and uploaded the tutorial.
> > I don't know how many people have visited or made
> > changes.  After all that I look at the current
> > 2.5 docs, and what do I see?  The same, trivial,
> > problem is still there.

I agree with you generally on the "something needs to be done".  I'm
all for a system that allows people to make trivial changes
themselves, and has a team (or Czar) overseeing it to keep things in
order.

I disagree with some of the details of your suggestion as I tend to be
more in favour of a "Wild West Wiki" approach that gives everyone
equal power, except the editors who have final say.  However I'm
broadly in agreement.

Ironically, I think that if you and Fredric played nicely, you'd find
that he also broadly agrees with the need for change (hence the
creation of the wiki).

I think (but am not at all sure) that getting the people in change of
Python to change the way things are done is quite difficult.  I think,
just like with the standard library, that there tends to be a system
of seeing what gets created in the wild, and then once something is
fairly well proven, make it official.  I'm not at all sure that this
is a bad way of going about things.  DIY certainly seems to be a
large, but unspoken, part of the community.

If you want your changes to take place, you'll need to set it up
yourself, make it work, and if it did, it would very likely replace
the current system.  If it doesn't work, that would seem to suggest
that it wasn't sufficiently better.

I know it can be very frustrating making suggestions and comments on
the list and people at best ignoring them, but that seems to be how
things work around here.  I think it's a zen thing.

> [snipped...a proposal that would hopefully
> improve the documentation and process.]
>
> No comments on this either.  I wonder why?
>
> ...It is a lousy or unworkable idea.
>
> ...Fredrik doesn't like it.
>
> ...It did not come from an insider.
>
> ...The docs for introducing people to Python
> and getting them to an intermediate level are
> already ok.  Any further improvement would
> erode the status of the existing experts and
> is thus undersireable.
>
> ...Same as above but would reduce the ability
> of experts to make money writing commercial
> books.

Probably none of the above.  It's just not exciting enough for people
to go away and do it for you.  If you really believe in the idea, do
it, prove it and then people will accept it (and you'll probably be in
charge of the docs).

Ed