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

[rurpy at yahoo.com]

Ed Singleton wrote:
> On 30 Mar 2006 16:30:24 -0800, rurpy at yahoo.com <rurpy at yahoo.com> wrote:
> >
> > What are you saying?  Ideas must come only from those
> > with the time and skill to implement them?  No one else
> > need apply?
>
> 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:
- 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.
- 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.
- 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.
- Without outside ideas and critisism the core
  development group can become "inbred" and loose touch
  with the user community.
- Putting restrictions on who can contribute ideas is
  often just human psycological desire for exclusion and
  control.
- Using an open forum like usenet means you *will*
  get ideas and critisism from "unworthy" people.  Group
  think and intimidation can reduce but not eliminate it.

> If you want
> someone else to do the acting upon for you, for free

This is what is tripping you up.  You interpret my
critisism as a demand that "you" (plural) do something.
First it is not a demand.  It is (to use your terminology
below), a gift.  You want to ignore it?  Fine.  You
want to delete all documentation and say, "well that
will teach to complain!"  Fine.  You want to add it
to actual or mental list of things to think about.
Fine.  You want to encourage people to discuss it
leading (hopefully) to someone doing something
about it?  Fine.

I was once involved periperaly in the UI part of a
software project.  The hardest part was finding out
what problems users had with the ui and documentation.
The company had a bunch of very expensive engineers
and tech writers sit down with a group of potential
users (also expensive), for several weeks, studying
what problems the users had, what was confusing or
not clear, what was liked and not liked.  Obtaining
this info was very expensive.  The results were
excellent.

I suggest when that kind of info is offered to you
for free on usenet, you might want to take advantage
of it.

> (and probably for no thanks),

Do you think you know me well enough from a
handful of usenet postings to conclude that?

> then it has to be one hell of an amazing idea that no one
> else has ever had (which, trust me, you won't have, and neither,
> probably, will I).

I definately won't, but you (with low probability) might?
Well, at least your digs are more subtle than Fredrik's. :-)

> Everyone knows how to improve open source software, but what good is
> that to anyone?  Making the improvements is worth hell of a lot and
> that's why the people who do develop a lot of kudos in the community
> (it's about the only payment they get for it, and they do deserve it).

Of course they do.  But that does not extend to
being silent about problems.

> If you have an idea, then good for you, but make some small attempt to
> do something about it yourself.

Prehaps you missed my post where I suggested a concrete
textual correction.  And offered to change the source
myself if the developers are too busy?  Or perhaps you
missed the patches I submitted to correct other issues
with the docs that have been sitting there for four
months?

> I'm not much of an expert in anything yet, but I had an idea, and then
> managed to put the documents in a wiki, which was at least trying to
> do something.  Fredrik beat me to it and did a much better job, but
> even so I feel quite proud that I did something and tried to move
> things on, rather than just post to a mailing list and hope someone
> else does it.

I'm sorry, I don't buy your "just do it" philosophy.
For one, its often not possible.  (E.g. my offer to
make a doc correction if given cvs access.)  For another,
"just do it" without thought, discussion with others,
etc will most often lead to a half-assed solution, or
a waste of time because everyone else rejects the work.

And you are misrespresenting me by saying "...just
post to a mailing list and hope someone else does it."
I offered in many previous posts and the post you
responded to, to actually do some work.

> > Whenever anyone criticizes anything about free software
> > there are three automatic responses:
> >
> > 1. You are an idiot if you can't understand / have a problem with that.
> > 2. Its free so you should be grateful and shutup.
> > 3. You have the source, change it yourself, you lazy whiner.
>
> Whenever people are rude to you, it's quite useful to stop and think
> why.  Quite often you'll find that it's something you're doing wrong.

Yup,  Continual self examination is a good thing.

> If it happens every single time you make a criticism, then it's
> definitely something you are doing wrong.

You are flat wrong here.  A cursory look at any
history book will show dozens of examples where
people who stood up for what came to be seen as
right, had to do so alone, against critisism,
personal attacks, and sometimes at the cost of
their lives.

(No, people on usenet are not substantialy different
than people in history books)
(No I am not a crusader or see myself as one.  I just
do not give a rat's ass about following the party line.)

>...
> If someone came to me with a gift, should I take it and start pointing
> out all it's flaws and demanding that they fix the flaws?

Bad analogy.  Python is not a "gift" that was given
to me.  Guido did not get up one morning and say,
"I think I will develop a new language for Rurpy".
I doubt he ever thought, "I think I'll develop a
new langauage for all my friends, and make the world
a better place".  I guess that he and the other Python
contributors contribute for the same reasons most open
source developers do, dissatifaction with current
langauges, a desire to improve their own environment,
a desire for status, a desire to see their ideas put
into practice.  (Another darker motivation in some
projects, not Python I think, is, sadly, a desire
to use open source to make lots of money by getting
free labor.)

Of course I don't know Guido et.al. so this is speculation,
but there is a lot written about motivation in the free
software world in general.

That it is not a gift can also be confirmed on the
Python.org website:
  Python Success Stories
  Python is part of the winning formula for productivity,
  software quality, and maintainability at many companies
  and institutions around the world.

The trouble is, you want it both ways.  You want to
present Python as a industrial strength language on
a par with commercial offerings, but when someone
looks at Python with the same critcal eye they would
look at a commercial product with, you switch back
to the "it's a gift, how dare you criticize it!" mode.
It you want Python to be considered a serious
"real world" language, you'd do better to argue
factually and credibly that x is not a problem,
or admit it is a problem and be open to suggestions
about how to fix it.