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

[Ed Singleton]

On 30 Mar 2006 16:30:24 -0800, rurpy at yahoo.com <rurpy at yahoo.com> wrote:
>
> "Fredrik Lundh" wrote:
> > rurpy at yahoo.com wrote
> > > write a tutorial as good as what is already there.  But what I can
> > > do is report problems I find when using it, and make suggestions
> > > about how to avoid those problems.
> >
> > There's no shortage of ideas -- nor people who can write a tutorial
> > that's better than the current one (which is far from optimal, mostly
> > thanks to a zillion peephole edits over the years).  There's a shortage
> > of volunteer time, though.  That's why the "I'm just the idea guy,
> > someone else will have to provide the hundreds of hours required
> > to implement my idea" arguments are so offensively meaningless.
>
> 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.  If you want
someone else to do the acting upon for you, for free (and probably for
no thanks), 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).

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).

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

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.

> 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. 
If it happens every single time you make a criticism, then it's
definitely something you are doing wrong.

> You could save everyone time and bandwidth by just
> responding with "#3!!!"
>
> Sorry Fredrik, truth is truth.  If there is a problem then people
> are right to point it out.  If that is really a big problem for
> you then I suggest setting up a forum or mailing list on
> python.org where you can delete "improper" messages,
> and ban posters who have "incorrect" attitudes.

Unfortunately just saying "truth is truth" doesn't make something
true.  If you really feel that people are right to point out problems
whenever they see them without making any attempt to correct them,
then at least attempt to prove your point with some sort of argument.

Do you think I would be right to point out every time I saw a problem
with your attitude or personality?  Of course I wouldn't.

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?

Imagine that free software is a gift to you that has taken many
thousands of hours to create.  If you're going to ask the giver to do
a better job of the gift that they've given you, you better ask in a
very, very, very nice way and you should probably show that you've at
least made some effort to correct the problem yourself, (and really
you'd be better of just asking how to fix the problem yourself. 
People are quite responsive to that.  They always want more helpers).

> > Come up with an idea that *reduces* the overall work needed to write
> > and maintain a good manual, and people might start listening to what
> > you have to say.
>
> What makes you think there is such a way?  Don't you
> think publishers have been looking for that way for years?
> Do you think it possible that a good manual might just
> require good writers, and good editors, and it would make
> sense to encourage those who might be interested, rather
> than posting put-downs of anyone who misreads or
> misinterprets the docs?

If you think that publishers are the apex of discovering new ways to
write docs then you don't have much experience of the real world.  Any
business process like that tends to be quite a good distance (around
5-10 years) behind the head of the pack.  And if you think we have
somehow reached perfection in the process of creating documents...

Fredrik does encourage people who might be interested.  Go back and
read this thread again.  Maybe he knows that you're not actually
interested in contributing.



> > Or come up with some money.  If you can fund a technical writer for
> > one year, there are lots of things that could be done.
> >
> > > But the perception I get here, from responses like yours,
> > > is that such suggestions are unwelcome, and unlikely
> > > to be acted upon.  I gather corrections of factual
> > > errors are welcome, but stylistic, or organizational
> > > ones are not.  And the latter kind of changes, applied
> > > extensively to all the docs, are what will make a big
> > > improvement.  Difficult at best, but absolutely impossible
> > > if you and the other powers-that-be are happy with
> > > the status-quo.
> >
> > The problem with people like you is that you are completely ignoring
> > all the hard work done by the people who build the free stuff that
> > anonymous cowards like you like to complain about.
>
> Yes, here comes #3.  I am not ignoring that at all.  I am very
> applicative.  But that appreciation does not extend to
> supplication, or censorship.  And save your name-calling for
> someone who is bothered by it.
>
> > Luckily, most people are not like you.  If they were, nothing would
> > ever happen.
>
> In the time you've spent posting about this, you or someone
> else with svn access to the docs, could have simply gone
> and made the change.  Admittedly most changes would
> require more process but there are many like this just require
> someone to DO IT.  Give me svn access, and I will.  But I
> guess for you it is more fun to write wikis and things than
> actually fixing the doc.  (Don't get me wrong, I hope the
> wiki thing works and I will contribute but note what I wrote
> initially about programming Python being more fun than
> dealing with that grungy english *writing* yeck!)

In the time he spent posting about this something got done.  An entire
new process got created, so that anyone can make changes.  If the
changes really are useful, then either the wiki version will become
official, or people will just start pointing newcomers to the wiki
version instead.

Go to the wiki, make the changes you want, and feel good about
yourself for once.

Ed