Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
[EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
"Fredrik Lundh" <[EMAIL PROTECTED]> 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
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? -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
[EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
"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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
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"...) -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
[EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
[EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: QOTW... (was: Doc suggestions (was: Why "class exceptions" are not deprecated?))
[EMAIL PROTECTED] wrote: > > "Ed" == Ed Singleton <[EMAIL PROTECTED]> 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
Ed Singleton wrote: > On 30 Mar 2006 16:30:24 -0800, [EMAIL PROTECTED] <[EMAIL PROTECTED]> 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.
QOTW... (was: Doc suggestions (was: Why "class exceptions" are not deprecated?))
> "Ed" == Ed Singleton <[EMAIL PROTECTED]> writes: Ed> Go to the wiki, make the changes you want, and feel good about Ed> yourself for once. +1 QOTW. Skip -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
On 30 Mar 2006 16:30:24 -0800, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > > "Fredrik Lundh" wrote: > > [EMAIL PROTECTED] 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
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
> 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
[EMAIL PROTECTED] 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." -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
"Fredrik Lundh" wrote: > [EMAIL PROTECTED] wrote > > Fredrik Lundh wrote: > > > [EMAIL PROTECTED] 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!) -- http://mail.python.org/mailman/listinfo/python-l
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
"Terry Reedy" wrote: > <[EMAIL PROTECTED]> wrote in message > news:[EMAIL PROTECTED] > > 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
"Terry Reedy" wrote: > <[EMAIL PROTECTED]> wrote in message > news:[EMAIL PROTECTED] > > 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
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)) 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
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. > > 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
On 29/03/06, Fredrik Lundh <[EMAIL PROTECTED]> 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
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? -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
On 29/03/06, Ed Singleton <[EMAIL PROTECTED]> wrote: > On 29/03/06, Fredrik Lundh <[EMAIL PROTECTED]> 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 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 > Also, your looks better than mine. Did you write a script to do the table of contents too? Ed -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
On 29/03/06, Fredrik Lundh <[EMAIL PROTECTED]> 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 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
> 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
>> (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/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
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! -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
On 29/03/06, Fredrik Lundh <[EMAIL PROTECTED]> wrote: > [EMAIL PROTECTED] 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). -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
[EMAIL PROTECTED] wrote > Fredrik Lundh wrote: > > [EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Doc suggestions (was: Why "class exceptions" are not deprecated?)
<[EMAIL PROTECTED]> wrote in message news:[EMAIL PROTECTED] > Fredrik Lundh wrote: >> [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list
Doc suggestions (was: Why "class exceptions" are not deprecated?)
Fredrik Lundh wrote: > [EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
