Why "class exceptions" are not deprecated?

[Gregory Petrosyan]

1) From 2.4.2 documentation:
There are two new valid (semantic) forms for the raise statement:
raise Class, instance
raise instance

2) In python:

raise NameError Traceback (most recent call last):
File "<stdin>", line 1, in ?
NameError help(NameError) Help on class NameError in module exceptions: ... raise 0

Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: exceptions must be classes, instances, or strings
(deprecated), not i
nt

So, if it's a bug in documentation, it should be corrected. Otherwise,
(IMHO!) raising classes should be deprecated. Does raising class make
sence? As for me, I can't find any usefull case for it.

[Fredrik Lundh]

Gregory Petrosyan wrote:

1) From 2.4.2 documentation:
There are two new valid (semantic) forms for the raise statement:
raise Class, instance
raise instance

2) In python:

raise NameError Traceback (most recent call last):
File "<stdin>", line 1, in ?
NameError help(NameError) Help on class NameError in module exceptions: ... raise 0

Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: exceptions must be classes, instances, or strings
(deprecated), not i
nt

So, if it's a bug in documentation, it should be corrected. Otherwise,
(IMHO!) raising classes should be deprecated.

it could be that the tutorial author expected you to read chapter 8
before you read chapter 9, and used "new" to mean forms that hadn't
already been described:

http://docs.python.org/tut/node10.html
Does raising class make sence? As for me, I can't find any usefull
case for it.

as explained in the language reference,

raise Class

is the same thing as

raise Class()

</F>

[Gregory Petrosyan]

Thanks for answer. But what about "Explicit is better than implicit"?

[Gregory Petrosyan]

"The first argument to raise names the exception to be raised. The
optional second argument specifies the exception's argument.
Alternatively, the above could be written as raise
NameError('HiThere'). Either form works fine, but there seems to be a
growing stylistic preference for the latter."

Are there any deprecation plans?

[Fredrik Lundh]

Gregory Petrosyan wrote:

Thanks for answer. But what about "Explicit is better than implicit"?

"Practicality beats purity"

Changing the language just because some random guy on a newsgroup
read the tutorial backwards isn't really practical.

</F>

[Steven Bethard]

Gregory Petrosyan wrote:

1) From 2.4.2 documentation:
There are two new valid (semantic) forms for the raise statement:
raise Class, instance
raise instance

Check `PEP 8`_ -- the latter form is preferred:

"""
When raising an exception, use "raise ValueError('message')" instead of
the older form "raise ValueError, 'message'".
"""

... _PEP 8: http://www.python.org/dev/peps/pep-0008/

STeVe

[Terry Reedy]

"Gregory Petrosyan" <gr***************@gmail.com> wrote in message
news:11*********************@g10g2000cwb.googlegro ups.com...

Are there any deprecation plans?

In Python 3, many redundant options will likely be eliminated, including
some for the raise statement.

[rurpy]

Fredrik Lundh wrote:

Gregory Petrosyan wrote:

1) From 2.4.2 documentation:
There are two new valid (semantic) forms for the raise statement:
raise Class, instance
raise instance

2) In python:

>> raise NameError

Traceback (most recent call last):
File "<stdin>", line 1, in ?
NameError

>> help(NameError)

Help on class NameError in module exceptions: ...

>> raise 0

Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: exceptions must be classes, instances, or strings
(deprecated), not i
nt

So, if it's a bug in documentation, it should be corrected. Otherwise,
(IMHO!) raising classes should be deprecated.

it could be that the tutorial author expected you to read chapter 8
before you read chapter 9, and used "new" to mean forms that hadn't
already been described:

http://docs.python.org/tut/node10.html

Does raising class make sence? As for me, I can't find any usefull
case for it.

as explained in the language reference,

raise Class

is the same thing as

raise Class()

The OP points out an ambiguity in the docs, and as usual,
gets told he can't read, etc. How typical. Maybe if comments
like this were encouraged and acted upon, the docs would be
a little better than they are. But I guess the current practice
of intimidation has benefits too in that it allows the response,
"nobody has complained, so the docs must be really great
and we can go on writing Python instead of that grungy
English."

And maybe if there were a decent language reference manual
people wouldn't be so inclined to use the Tutorial as one, with
the resultant out-of-sequence reading.

[Fredrik Lundh]

ru***@yahoo.com wrote:

The OP points out an ambiguity in the docs, and as usual,
gets told he can't read, etc. How typical.
where did anyone tell the OP that he can't read? it's pretty clear
that you have trouble reading things without mixing them up with
your own preconceptions, but we already knew that.
Maybe if comments like this were encouraged and acted upon

do you think your posts would look any different if we replaced you
with a markov generator and fed it with your old posts ?

if you want to contribute, contribute. a new tutorial would be great.
get to work!

</F>

[rurpy]

Fredrik Lundh wrote:

ru***@yahoo.com wrote:

The OP points out an ambiguity in the docs, and as usual,
gets told he can't read, etc. How typical.
where did anyone tell the OP that he can't read?

"it could be that the tutorial author expected you
to read chapter 8 before you read chapter 9,..."

"...because some random guy on a newsgroup read
the tutorial backwards..."
it's pretty clear
that you have trouble reading things without mixing them up with
your own preconceptions, but we already knew that.111

Maybe if comments like this were encouraged and acted upon

do you think your posts would look any different if we replaced you
with a markov generator and fed it with your old posts ?

if you want to contribute, contribute. a new tutorial would be great.
get to work!

I don't want to, and probably couldn't, 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. For example, the
sentence in question,

"There are two new valid (semantic) forms for the
raise statement: "

could be replaced with

"There are two other forms for the raise statement
in addition to the one described in chapter 8:"

or

"Two new forms for the raise statement were introduced
in Python verion 2.x:"

depending on what the meaning of "new" is in the
original sentence. (I'm still not sure, but your post
implies it is the former.)

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.

[Terry Reedy]

<ru***@yahoo.com> wrote in message
news:11**********************@i39g2000cwa.googlegr oups.com...

Fredrik Lundh wrote:

ru***@yahoo.com wrote:
where did anyone tell the OP that he can't read?
"it could be that the tutorial author expected you
to read chapter 8 before you read chapter 9,..."

This actually acknowledges an ability to read ;-)
-- that just was not exercised sufficiently (in his opinion) ...
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. For example, the
sentence in question,

"There are two new valid (semantic) forms for the
raise statement: "

could be replaced with

"There are two other forms for the raise statement
in addition to the one described in chapter 8:"
That said, and without looking at the context in the doc, this looks like
an improvement.
or

"Two new forms for the raise statement were introduced
in Python verion 2.x:"
This is incorrect, I believe.
depending on what the meaning of "new" is in the
original sentence. (I'm still not sure, but your post
implies it is the former.)
I agree that the current text seems ambiguous.
But the perception I get here, from responses like yours,
is that such suggestions are unwelcome, and unlikely
to be acted upon.
FL is not the main doc maintainer. Even if you were to be correct about
his views, premature generalization is the source of much error.
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.

If you wish to become a volunteer Python improver, let me know either here
or privately and I will respond with a suggestion and an offer.

Terry Jan Reedy

[Fredrik Lundh]

ru***@yahoo.com wrote

Fredrik Lundh wrote:

ru***@yahoo.com wrote:

The OP points out an ambiguity in the docs, and as usual,
gets told he can't read, etc. How typical.
where did anyone tell the OP that he can't read?

"it could be that the tutorial author expected you
to read chapter 8 before you read chapter 9,..."

What makes you so sure that wasn't a statement about the tutorial ?
"...because some random guy on a newsgroup read
the tutorial backwards..."
Does the word "context" mean anything to you? or the word "de-
precation", that was used multiple times by the OP ? Or the phrase
"changing the language", that you cut out from that quote.
I don't want to, and probably couldn't
That's pretty obvious.
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.

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.

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.

Luckily, most people are not like you. If they were, nothing would
ever happen.

</F>

[Ed Singleton]

On 29/03/06, Fredrik Lundh <fr*****@pythonware.com> wrote:

ru***@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.

I'm not entirely sure there is a shortage of people who want to
volunteer, just that a lot don't know that they can volunteer, and
those that do can't make a huge time commitment or don't have the
confidence.

I think there's quite a lot of people who would be happy to help out
as and when they could (particularly with small edits like the one
mentioned), if they were sure someone else was going to double check
that they hadn't accidentally written garbage.

This would be a perfect situation for a wiki. I think it would be a
good experiment to have a wiki containing the documentation (separate
from the main documentation and clearly marked experimental for the
moment), and to see if it did self-organise as wikis often do.
Beginners like rurpy could add comments when they don't understand a
paragraph, more confident people could attempt to correct the
paragraph, and every now and then an advanced person could scan
through it and make sure it was truly accurate.

It would greatly reduce the work need by the people currently
responsible for documentation (they just have to read through and make
sure things are correct) and if a page has been significantly improved
by the community and double checked by an expert, it could be promoted
to the official version of the documentation.

If the whole thing descends into chaos, the wiki (pages) could just be
deleted and we continue with the current system.

As Python has such an excellent community, it would be a shame not to
give them more responsibility in this area, and this system seems to
be working quite well for many python projects (many just use the wiki
in Trac).

Ed

(I'm actually tempted to just copy and paste each page from the
tutorial into the current wiki but I'd hate for it all to be deleted
after doing that).

[Fredrik Lundh]

Ed Singleton wrote:

This would be a perfect situation for a wiki. I think it would be a
good experiment to have a wiki containing the documentation (separate
from the main documentation and clearly marked experimental for the
moment), and to see if it did self-organise as wikis often do.
agreed.
It would greatly reduce the work need by the people currently
responsible for documentation (they just have to read through and make
sure things are correct) and if a page has been significantly improved
by the community and double checked by an expert, it could be promoted
to the official version of the documentation.
absolutely.

(and promoting could simply be done by tagging a given wiki revision as
the official source, using something like http://effbot.org/django-pageview
or a static version thereof, as the front-end renderer)
If the whole thing descends into chaos, the wiki (pages) could just be
deleted and we continue with the current system.

As Python has such an excellent community, it would be a shame not to
give them more responsibility in this area
the entire python.org site (and Python) would benefit for improved support
for micro-contributions, but I doubt that will ever happen under the current
regime.
(I'm actually tempted to just copy and paste each page from the
tutorial into the current wiki but I'd hate for it all to be deleted
after doing that).

just do it!

</F>

[Fredrik Lundh]

>> (I'm actually tempted to just copy and paste each page from the

tutorial into the current wiki but I'd hate for it all to be deleted
after doing that).

just do it!

btw, one alternative could be to use an infogame site for this purpose:

http://infogami.com

this gives you revision history, a permissions system (limiting editing to
registered users might be a good idea), comments, an associated blog,
voting, feeds, change logs, etc.

to convert the current tutorial to infogami-compatible markup, use this:

http://www.aaronsw.com/2002/html2text/

</F>

[Fredrik Lundh]

> btw, one alternative could be to use an infogame site for this purpose:

http://infogami.com

this gives you revision history, a permissions system (limiting editing to
registered users might be a good idea), comments, an associated blog,
voting, feeds, change logs, etc.

alright, I got bored and uploaded a copy of the current Python tutorial to

http://pytut.infogami.com

</F>

[Ed Singleton]

On 29/03/06, Fredrik Lundh <fr*****@pythonware.com> wrote:

btw, one alternative could be to use an infogame site for this purpose:

http://infogami.com

this gives you revision history, a permissions system (limiting editingto
registered users might be a good idea), comments, an associated blog,
voting, feeds, change logs, etc.

alright, I got bored and uploaded a copy of the current Python tutorial to

http://pytut.infogami.com

Damn. You beat me to it by an hour.

http://singletoned.infogami.com/_special/index

I had a nightmare with character encodings (mainly because I'm
terrible with them). I have a script written that does it all for me,
but it keeps choking on characters. I just tried randomly converting
things to Unicode at various points for over an hour until it worked.

Ed

[Ed Singleton]

On 29/03/06, Ed Singleton <si*********@gmail.com> wrote:

On 29/03/06, Fredrik Lundh <fr*****@pythonware.com> wrote:

btw, one alternative could be to use an infogame site for this purpose:

http://infogami.com

this gives you revision history, a permissions system (limiting editing to
registered users might be a good idea), comments, an associated blog,
voting, feeds, change logs, etc.

alright, I got bored and uploaded a copy of the current Python tutorialto

http://pytut.infogami.com

Damn. You beat me to it by an hour.

http://singletoned.infogami.com/_special/index

I had a nightmare with character encodings (mainly because I'm
terrible with them). I have a script written that does it all for me,
but it keeps choking on characters. I just tried randomly converting
things to Unicode at various points for over an hour until it worked.

Ed

Also, your looks better than mine. Did you write a script to do the
table of contents too?

Ed

[Fredrik Lundh]

Ed Singleton wrote:

alright, I got bored and uploaded a copy of the current Python tutorial to

http://pytut.infogami.com
Damn. You beat me to it by an hour.

http://singletoned.infogami.com/_special/index

oops. sorry for that.

I had a nightmare with character encodings (mainly because I'm
terrible with them). I have a script written that does it all for me,
but it keeps choking on characters. I just tried randomly converting
things to Unicode at various points for over an hour until it worked.

sounds weird. iirc, there were only one page that contained non-ascii
characters, and the latest html2text.py script had no problems dealing
with that one.
Also, your looks better than mine.
did you look at it before or after I added the new stylesheet? ;-)
Did you write a script to do the table of contents too?

nope; I did that all by hand. I plan to write some scripts to get contents
*out* of infogami, though, but that'll have to wait for some other day.

anyway, do you want to keep your version, or should we "standardize" on
the pytut version ? and are there any willing community contributors out
there?

</F>

[Ed Singleton]

On 29/03/06, Fredrik Lundh <fr*****@pythonware.com> wrote:

Ed Singleton wrote:

alright, I got bored and uploaded a copy of the current Python tutorial to

http://pytut.infogami.com

Damn. You beat me to it by an hour.

http://singletoned.infogami.com/_special/index

oops. sorry for that.

Not at all. I'm quite proud that it was only an hour.

I had a nightmare with character encodings (mainly because I'm
terrible with them). I have a script written that does it all for me,
but it keeps choking on characters. I just tried randomly converting
things to Unicode at various points for over an hour until it worked.
sounds weird. iirc, there were only one page that contained non-ascii
characters, and the latest html2text.py script had no problems dealing
with that one.

node4 and node5 caused problems for me. I'm still struggling a bit
with character encodings so that probably caused most of my problems.
Also, your looks better than mine.

did you look at it before or after I added the new stylesheet? ;-)

Before. Now it looks gorgeous.

Did you write a script to do the table of contents too?

nope; I did that all by hand. I plan to write some scripts to get contents
*out* of infogami, though, but that'll have to wait for some other day.

anyway, do you want to keep your version, or should we "standardize" on
the pytut version ? and are there any willing community contributors out
there?

Standardise on yours obviously, though I might keep mine around to
keep playing with the script. It's a bit clumsy at the moment, but I
can see there's some potential there for having a general script to
rip content out of sites and put it in a wiki (if only for the rest of
the python docs, should this project succeed). I'd also be interested
in seeing how you did it as it would be the first time I could
directly compare what I did to how an expert does it.

I'd suggest adding some sort of guidance page so that people know
roughly what's expected. IE can they just add questions and comments
into the text, hoping that someone more knowledgeable will sort it out
(or delete it).

Ed

[Fredrik Lundh]

Ed Singleton wrote:

I'd suggest adding some sort of guidance page so that people know
roughly what's expected. IE can they just add questions and comments
into the text, hoping that someone more knowledgeable will sort it out
(or delete it).

I've added some notes to the front-page. feel free to tweak/clarify (or post
comments here or on the site).

for now, I think it's worth trying to keep the text clean and reasonably read-
able at all times, and use the comment function to add questions/suggestions
(more wikipedia than c2, in other words).

more later.

</F>

[Gerard Flanagan]

Fredrik Lundh wrote:

Ed Singleton wrote:

I'd suggest adding some sort of guidance page so that people know
roughly what's expected. IE can they just add questions and comments
into the text, hoping that someone more knowledgeable will sort it out
(or delete it).

I've added some notes to the front-page. feel free to tweak/clarify (or post
comments here or on the site).

for now, I think it's worth trying to keep the text clean and reasonably read-
able at all times, and use the comment function to add questions/suggestions
(more wikipedia than c2, in other words).

more later.

</F>

I like it!

Can a page be easily recovered if someone decided to delete it?

Can anyone add a page? How to do this?

Would it be a good idea to make every subsection of a page linkable?
eg.

http://pytut.infogami.com/node6.html#the_range_function

then a list of the subsections at the top of each page? For example
I've added such a list at http://pytut.infogami.com/node6.html

Gerard

[Fredrik Lundh]

Gerard Flanagan wrote:

I've added some notes to the front-page. feel free to tweak/clarify (or post
comments here or on the site).

for now, I think it's worth trying to keep the text clean and reasonably read-
able at all times, and use the comment function to add questions/suggestions
(more wikipedia than c2, in other words).
I like it!

thanks!

the feedback this far has been very positive, and there's been quite a
few good contributions from several contributors. makes me wonder why
I haven't done this before (could it be that infogami didn't exist last time
I looked into edit-through-the-web stuff ? ;-)
Can a page be easily recovered if someone decided to delete it?
yup. infogami keeps a full history.
Can anyone add a page? How to do this?
just add a [[link]] to a page (or comment), and click on the link to get an
offer to create the missing page. or just hack the URL. see:

http://howto.infogami.com/createnewpages

however, I would prefer if we could keep the current overall structure intact
for now. (but adding new pages for other purposes is perfectly okay, though;
also see the "if you want to make major changes" note on the front page).
Would it be a good idea to make every subsection of a page linkable?
eg.

http://pytut.infogami.com/node6.html#the_range_function

then a list of the subsections at the top of each page? For example
I've added such a list at http://pytut.infogami.com/node6.html

the subsections should absolutely be linkable in the finished python.org
product, but that can be automated (either in the yet-to-be-written export
scripts, or by some wikipedia-style infogamibot maintenance droid... (1))

</F>

1) dear lazyweb/lazynet: does anyone have some time to spare on figuring
out how to log into infogami from a simple python script. standard library
only, preferrably.

[rurpy]

"Terry Reedy" wrote:

<ru***@yahoo.com> wrote in message
news:11**********************@i39g2000cwa.googlegr oups.com...

Fredrik Lundh wrote: But the perception I get here, from responses like yours,
is that such suggestions are unwelcome, and unlikely
to be acted upon.

FL is not the main doc maintainer. Even if you were to be correct about
his views, premature generalization is the source of much error.

Not sure how premature it is. I've been reading
c.l.p. on and off for nearly a year.

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.

If you wish to become a volunteer Python improver, let me know either here
or privately and I will respond with a suggestion and an offer.

Yes, please do. I'm sure it would be helpful, not only
for me but for everyone dissatified with the current
documentation and wanting to help, to hear your
suggestion / offer.

[rurpy]

"Terry Reedy" wrote:

<ru***@yahoo.com> wrote in message
news:11**********************@i39g2000cwa.googlegr oups.com...

Fredrik Lundh wrote: But the perception I get here, from responses like yours,
is that such suggestions are unwelcome, and unlikely
to be acted upon.

FL is not the main doc maintainer. Even if you were to be correct about
his views, premature generalization is the source of much error.

Not sure how premature it is. I've been reading
c.l.p. on and off for nearly a year.

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.

If you wish to become a volunteer Python improver, let me know either here
or privately and I will respond with a suggestion and an offer.

Yes, please do. I'm sure it would be helpful, not only
for me but for everyone dissatified with the current
documentation and wanting to help, to hear your
suggestion / offer.

[rurpy]

"Fredrik Lundh" wrote:

ru***@yahoo.com wrote

Fredrik Lundh wrote:

ru***@yahoo.com wrote:
>
> The OP points out an ambiguity in the docs, and as usual,
> gets told he can't read, etc. How typical.

where did anyone tell the OP that he can't read?
"it could be that the tutorial author expected you
to read chapter 8 before you read chapter 9,..."

What makes you so sure that wasn't a statement about the tutorial ?

The word "you".

"...because some random guy on a newsgroup read
the tutorial backwards..."

Does the word "context" mean anything to you? or the word "de-
precation", that was used multiple times by the OP ? Or the phrase
"changing the language", that you cut out from that quote.

I wasn't commenting on the advisability of deprecating a
particular form of the raise statement. So why would I
leave that irrelevant material in the quote? I was commenting
on your remarks that the OP "read the tutorial backwards".
And pointing 1) there really was a specific problem in the
tutorial docs. 2) that a contributing factor was that there is
no good language reference. 3) That your caustic comments
were unwarranted and have a negative effect on people's
willingness to point out and fix doc problems.

I don't want to, and probably couldn't

That's pretty obvious.

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?

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.

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

[Fredrik Lundh]

ru***@yahoo.com wrote:

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.

as the old chinese proverb says, "Why bother teaching a man
to fish when you can just give him a fish."

</F>

[Fredrik Lundh]

1) dear lazyweb/lazynet: does anyone have some time to spare on figuring
out how to log into infogami from a simple python script. standard library
only, preferrably.

nevermind. the hack that didn't work yesterday did did work today. must
have been a bad cookie day.

</F>

[Ed Singleton]

On 30 Mar 2006 16:30:24 -0800, ru***@yahoo.com <ru***@yahoo.com> wrote:

"Fredrik Lundh" wrote:

ru***@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

[skip]

> "Ed" == Ed Singleton <si*********@gmail.com> writes:

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

+1 QOTW.

Skip

[rurpy]

Ed Singleton wrote:

On 30 Mar 2006 16:30:24 -0800, ru***@yahoo.com <ru***@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.

[rurpy]

sk**@pobox.com wrote:

>> "Ed" == Ed Singleton <si*********@gmail.com> writes:

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

+1 QOTW.

I suggest leaving off the "for once". Otherwise, it is just
another gratuitous insult, of the kind there is already too
many of in this newsgroup.

[Paul Boddie]

ru***@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

[Fredrik Lundh]

ru***@yahoo.com wrote:

(and probably for no thanks),

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

yes. anyone who's been involved with open source project long
enough has seen enough people like you to know you. you're not
unique, in any way.

</F>

[Fredrik Lundh]

Ed Singleton wrote:

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.

and for the record: the infogami setup had never happened if Ed hadn't
written that post.

(sure, the wiki idea isn't new, and I've been investigating edit-through-
the-web solutions a lot lately in response to the python.org fiasco, but
there's a lot of stop energy in the python universe these days. python
needs more "let's try it; it may work" and less "let's set up a committee
and thoroughly investigate all possible technical solutions before anyone
is allowed to do anything"...)

</F>

[rurpy]

"Fredrik Lundh" wrote:

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.
and for the record: the infogami setup had never happened if Ed hadn't
written that post.

I wouldn't rest on my laurels quite yet if I were you.
You've provided a good piece to take care of the input
collection side of the equasion but I've seen nothing
that deals with the output side (wiki -> docs). Are the
same people who don't have time to deal with doc patches
going to be sifting though the wiki entries, editing for
consistent style, etc, and updating the docs? Without
that we have just YAW (yet another wiki).

I notice that Postgresql has user-annotated pages. They
dump the added comments with each new doc point release
becauase it is too much work to merge them into the docs.
(sure, the wiki idea isn't new, and I've been investigating edit-through-
the-web solutions a lot lately in response to the python.org fiasco, but
there's a lot of stop energy in the python universe these days. python
needs more "let's try it; it may work" and less "let's set up a committee
and thoroughly investigate all possible technical solutions before anyone
is allowed to do anything"...)

The two approaches are often not mutually exclusive.

[Terry Reedy]

<ru***@yahoo.com> wrote in message
news:11**********************@t31g2000cwb.googlegr oups.com...

"Terry Reedy" wrote:
Not sure how premature it is. I've been reading
c.l.p. on and off for nearly a year.

Yes, there have been claims that doc patches have to be in Latex or are
otherwise not welcome. But these mostly (all?) have lacked relevant
concrete data, which would be actual responses to actual submissions to the
Python SourceForge change trackers.

There have also been fact-based postings at least partly refuting such
claims, including some by me.

> I gather corrections of factual
> errors are welcome, but stylistic, or organizational
> ones are not.

I would not be surprised if the volunteer doc editors see corrections and
the writing of missing docs as higher priority than sylistic upgrades, but
that is different from 'not welcome'.

Some time ago, Alex Martelli submitted several style change suggestions for
at least one of the docs. As I remember, at least most of them were
accepted. In any case, all were considered. And there have since been
other changes that I have been involved with that were arguably style
upgrades rather than corrections.

A few organizational changes might be considered, especially if accompanied
by an offer to make at least a prototype, but someone with fundamentally
different ideas should write their own doc under their own name.
If you wish to become a volunteer Python improver, let me know either
here or privately and I will respond with a suggestion and an offer.

Yes, please do.

Frederik has one idea. Here is what I was going to say, and will anyway.

Suggestion: You could submit the one improved sentence you previously
suggested. But the overhead of any change is a bit high for just that. So
gather at least a few suggestions, put them in order, include section
number and identifier for each, and cut-and-paste urls from current docs at
python.org.

Offer: If you submit your 'text patch' to SourceForge and let me know, I
will review it right away. If you prefer, post or email to me and I will
'pre' review it before submission. You can collect ideas from others if
you want; I only care about formating that make the proposed change sites
and contexts easy to find.

Terry Jan Reedy

[Kent Johnson]

Terry Reedy wrote:

Yes, there have been claims that doc patches have to be in Latex or are
otherwise not welcome.

This is counter to my own experience and this page which says, "There's
no need to worry about text markup; our documentation team will gladly
take care of that."
http://docs.python.org/about.html

Submitting a proposed change or fix is easier and quicker than arguing
about it on c.l.py and it seems to get pretty quickly to the actual
document maintainers.

Kent

[Fredrik Lundh]

ru***@yahoo.com wrote:

and for the record: the infogami setup had never happened if Ed hadn't
written that post.

I wouldn't rest on my laurels quite yet if I were you.
You've provided a good piece to take care of the input
collection side of the equasion but I've seen nothing
that deals with the output side (wiki -> docs).

no, but that's because you're the kind of pathetic loser who only sees
problem with things, and only pops up when you have a chance to piss
on something.

</F>

[rurpy]

"Terry Reedy" wrote:

<ru***@yahoo.com> wrote in message

"Terry Reedy" wrote:

Yes, there have been claims that doc patches have to be in Latex or are
otherwise not welcome. But these mostly (all?) have lacked relevant
concrete data, which would be actual responses to actual submissions to the
Python SourceForge change trackers.
Yes, I have seen here many times, and read in the doc
footnotes, that any form of doc patches are acceptable.
I never thought or claimed otherwise.
...
Some time ago, Alex Martelli submitted several style change suggestions for
at least one of the docs. As I remember, at least most of them were
accepted. In any case, all were considered. And there have since been
other changes that I have been involved with that were arguably style
upgrades rather than corrections.
Given Alex Martelli's level of competence that is
neither surprising or representative.
A few organizational changes might be considered, especially if accompanied
by an offer to make at least a prototype, but someone with fundamentally
different ideas should write their own doc under their own name.
That puts a pretty high bar in place for the Language
Reference which has no hope if becoming good without
major organizational changes.
...
Suggestion: You could submit the one improved sentence you previously
suggested. But the overhead of any change is a bit high for just that. So
gather at least a few suggestions, put them in order, include section
number and identifier for each, and cut-and-paste urls from current docs at
python.org.
What I am questioning is why those barriers are so
high. Why does fixing a even a clear, obvious, fault
in the documentation require someone to log in to
sourceforge, create a bug or patch entry, have someone
else review it, comment it, change a half dozen words
in the source, close it... Why can't the folks doing
the docs be more proactive?
Offer: If you submit your 'text patch' to SourceForge and let me know, I
will review it right away. [...]

I appreciate the offer, but special treatment for
someone who raises a public stink is not going to
fix the underlying problem, is it?

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.

Am I the only one who sees something wrong with
this picture?

That change was simple and uncontroversial enough
so that someone should have simply done it. Why
is a formal change procedure needed for this level
of change? My guess is the people taking care of
the docs are Python developers whose main interest
is Python but who also generously volunteer to
handle docs issues. And probably most don't even
read c.l.p. Is that close?

Around christmas time there was a long discussion
here and on the python doc mailing list about how
to fix things. I was gone at the time but I read
a lot of it when I returned. One thing stuck out
like a sore thumb. There were hundreds of messages
about redit vs latex, html vs xml, toolchains, wikis,
patch managers, software packages. There were
almost no messages about *WRITING* and *EDITING*.
Part of the problem is undeniably the need for a
good infrastructure. But...

The other half, which has been nearly unaddressed
as far as I can tell, is PEOPLE! The docs problem
is a people problem, and won't be solved by technology.
(Unless someone here is very good with AI :-)

Here is how I would arrange things if I could...
===================================

A psf project or sig or some other discrete unit
chartered to work on the docs.

Active, encouraging, solicitation of people with
good (natural) language skills to participate.

Detailed written style guidelines and document
scopes so that everyone is, if not on, at least
near the same page.

Division of volunteers into (roughly)
Czar or small committee,
Editors,
Writers,
Everyone else.

Top level czar or small committee sets overall doc
policy and standards, resolves differences of opinion.

Editors responsible for ensuring the docs have
consistent style and appropriate content/level.
(By rewriting and editing more than by rejecting
submissions.)

Writers who create new material and correct/improve
existing material.

Everyone else who will be encouraged to report doc
errors, unclarities, suggest improvements, etc.

Specific areas of interest assigned publicly to
specific writers/editors (voluntarily of course),
both to provide them with public recognition and
as a minor incentive for them to get something done.

A definition of what constitutes an minor change
and the ability of volunteers to make such changes
unilaterally.

Facilitation of a fast-path communication channel
between the person maintaining the docs for a package,
and the developers/maintainers of that package, so
questions can get asked and answered quickly.

Use of a wiki or similar for:
- Collaborative work among the writer and editors
- Collection of comments and suggestions from users
about both the released python docs, and the
in-progress fixes/improvements (this part is what
FL has prototyped).

Foster a nurturing environment where people are
not afraid to make changes.

================================
This may be too top heavy for some people.
But the bottom line is that an effort has to be made
to get PEOPLE involved in WRITING and EDITING.
I personally think it will require more than waiting
for a wiki to self-organise.

[rurpy]

Fredrik Lundh wrote:

no, but that's because you're the kind of pathetic loser who only sees
problem with things, and only pops up when you have a chance to piss
on something.

Are you going to address the issue, or just limit
yourself to a public temper tantrum?

[Fredrik Lundh]

ru***@yahoo.com wrote:

no, but that's because you're the kind of pathetic loser who only sees
problem with things, and only pops up when you have a chance to piss
on something.

Are you going to address the issue, or just limit
yourself to a public temper tantrum?

what issue? your inability to contribute anything but complaints? that's
your problem, and you have to fix that yourself. I'm sure you'd feel better
if you tried.

</F>

[Paul Rubin]

"Fredrik Lundh" <fr*****@pythonware.com> writes:

what issue? your inability to contribute anything but complaints? that's
your problem, and you have to fix that yourself. I'm sure you'd feel better
if you tried.

I'm not sure what's wrong with complaints. I've submitted a lot of
bug reports and they weren't always handled the way I might have
liked, but nobody got after me for failing to submit fixes along with
them.

[rurpy]

Context: I entered this thread complaining about a
derogatory reply to a poster saying that he failed to
read the documentation correctly, when in fact the
documentation was faulty.

This reply on the Fedora list makes an interesting
contrast to c.l.p.

[description of problems OP had installing Fedora]
In summary, all the info was there, it was just hard to find for a
newbie or someone suffering from a particularly bad brain cramp.

Copying to fedora-docs list. Thanks for the feedback.

[rurpy]

<ru***@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.

Am I the only one who sees something wrong with
this picture?

I have not seen any responses to this so
maybe I am the only one.

Or has Fredrik Lundh's vitriolic postings
intimidated this entire group into silence?

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

[Ed Singleton]

On 4 Apr 2006 15:18:27 -0700, ru***@yahoo.com <ru***@yahoo.com> wrote:

<ru***@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