Why "class exceptions" are not deprecated?

F

Fredrik Lundh

Ed said:
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>
 
G

Gerard Flanagan

Fredrik said:
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
 
F

Fredrik Lundh

Gerard said:
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.
 
R

rurpy

Terry Reedy said:
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.
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.
 
R

rurpy

Terry Reedy said:
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.
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.
 
R

rurpy

Fredrik Lundh said:
(e-mail address removed) wrote

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

The word "you".
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.
That's pretty obvious.


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.


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!)
 
F

Fredrik Lundh

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>
 
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>
 
E

Ed Singleton

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


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.


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
 
S

skip

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

+1 QOTW.

Skip
 
R

rurpy

Ed said:
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 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.
 
R

rurpy

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

Paul Boddie

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
 
F

Fredrik Lundh

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>
 
F

Fredrik Lundh

Ed said:
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>
 
R

rurpy

Fredrik Lundh said:
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.
 
T

Terry Reedy

:
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 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.
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
 
K

Kent Johnson

Terry said:
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
 
F

Fredrik Lundh

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>
 
R

rurpy

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.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,982
Messages
2,570,186
Members
46,739
Latest member
Clint8040

Latest Threads

Top