Re: Do you feel bad because of the Python docs?
On Wed, 06 Mar 2013 03:12:43 +, Mark Lawrence wrote: On 06/03/2013 01:43, Bob Hanson wrote: [problem reporting bugs] You'll be delighted to know that everybody will have to sign a contributor agreement if they're supplying a patch file on the bug tracker, see http://blog.python.org/2013/03/introducing-electronic-contributor.html and http://mail.python.org/pipermail/python-dev/2013-March/124540.html Thanks, Mark. I have other responses to reply to, as well. I suspect that between your advice and the others, I'll learn how to help with at least doc bugs, soon. And sorry for the late reply. I changed ISPs (dialup to DSL) which turned out to be a major... uh... event for the geniuses at the telephone company out here in the frontier of the Oregon Cascades. Regards, Bob Hanson -- Sent from my Smart shoephone. Please excuse failure to top-post, failure to snip-to-context, and failure to leave message-digest subject header intact. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 06 Mar 2013 03:38:36 GMT, Steven D'Aprano wrote: On Tue, 05 Mar 2013 17:51:36 -0800, Bob Hanson wrote: [trouble reporting bugs] Works for me. Please try again, and if it still does not work, please email me off-list and I will help you either set up an account or report a tracker bug. Thanks, Steven. I'll likely take you up on your offer to help me off-list via email as I also wanted to talk with you about your circular-means function in your stats package. I do want to help with doc bugs. I'll probably have to get fairly involved to be able to submit more major doc-bug patches -- as others have said. And, as I said to Mark, sorry for the late reply. (I was without internet access for a few days while the experts at the phone company once again attempted to simulate minimal competence culminating with their DSL install expert -- who had never heard of Linux -- trying to puzzle out my desktop.) Regards, Bob Hanson -- Sent by smoke signals from the top of Mount St. Helens. Please excuse the sulfur fumes. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Sat, Mar 9, 2013 at 2:31 PM, Bob Hanson invalid@invalid.invalid wrote: (I was without internet access for a few days while the experts at the phone company once again attempted to simulate minimal competence culminating with their DSL install expert -- who had never heard of Linux -- trying to puzzle out my desktop.) I know exactly how that feels. Back in 2002 or thereabouts when we got our current Optus cable connection installed, we were an all-OS/2 shop (and we still have a good bit of OS/2, but there's some Windows and a good bit of Linux around now too). Rather than go through the hassle of having the guy try to figure out OS/2, we just rigged up a temporary Windows box and let him have his fun. Soon as he'd left, we unplugged the network cable from that machine and plugged it into our router (and then did a MAC address clone in the router, as for some reason the device was set to accept traffic only from the NIC the tech had installed). Funny, though, that Linux is still able to be obscure. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wed, 06 Mar 2013 18:50:35 -0500, Terry Reedy wrote: On 3/6/2013 2:48 PM, rh wrote: [Bob Hanson wrote:] I've tried twice to register with the bug tracker -- including just before sending this post. [...] [other details and errors snipped] I had wanted to report doc bugs, too, as I used to do copy and line editing. I seem to be able to find typos and such rather easily, but reporting said bugs -- not so easy. From http://docs.python.org/3/bugs.html Documentation bugs If you find a bug in this documentation or would like to propose an improvement, please send an e-mail to d...@python.org describing the bug and where you found it. If you have a suggestion how to fix it, include that as well. d...@python.org is a mailing list run by volunteers; your request will be noticed, even if it takes a while to be processed. For anything more than trivial changes (typos, grammar errors), a tracker issue is better. But the above is better than nothing. Thanks, Terry. I've been wanting to contribute for years, but a variety of issues (details of which are not relevant here) makes my helping improve the documentation probably the best fit for my abilities and situation. I do notice trivial changes, but I also feel some of the documentation could benefit from a much more thorough general editing to improve both ease of reading and general clarity. Contributing in this way sounds like I'll want to get more involved and probably do the contributor-signing thing and such -- or whatever steps I need to follow. And again, sorry for the late reply -- I was without internet for a few days while I changed ISPs. Regards, Bob Hanson -- Don't take yourself serious -- or no one else will. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 3/8/2013 11:12 PM, Bob Hanson wrote: I do notice trivial changes, I am currently set up again to do doc changes, so if you already have some non-controversial changes to the *current* docs, the online html versions, go ahead and email them to me. but I also feel some of the documentation could benefit from a much more thorough general editing to improve both ease of reading and general clarity. Big edits will need discussion on the tracker and will likely be opposed by someone. Contributing in this way sounds like I'll want to get more involved and probably do the contributor-signing thing and such -- or whatever steps I need to follow. Please do the agreement thing now. We just added the e-form a week ago and with that are getting more serious about asking for the agreements. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 3/6/2013 2:48 PM, rh wrote: I've tried twice to register with the bug tracker -- including just before sending this post. Both times I got something like this: Subject: Failed issue tracker submission From: Python tracker roundup-ad...@psf.upfronthosting.co.za Date: Wed, 06 Mar 2013 00:56:44 + An unexpected error occurred during the processing of your message. The tracker administrator is being notified. So, it's not all that easy to report bugs for me, anyway. I'd given up, prior, but reading this thread I thought I'd try one more time. I had wanted to report doc bugs, too, as I used to do copy and line editing. I seem to be able to find typos and such rather easily, but reporting said bugs -- not so easy. From http://docs.python.org/3/bugs.html Documentation bugs If you find a bug in this documentation or would like to propose an improvement, please send an e-mail to d...@python.org describing the bug and where you found it. If you have a suggestion how to fix it, include that as well. d...@python.org is a mailing list run by volunteers; your request will be noticed, even if it takes a while to be processed. For anything more than trivial changes (typos, grammar errors), a tracker issue is better. But the above is better than nothing. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, March 6, 2013 5:50:35 PM UTC-6, Terry Reedy wrote: If you find a bug in this documentation or would like to propose an improvement, please send an e-mail to d...@python.org describing the bug and where you found it. If you have a suggestion how to fix it, include that as well. That's great Terry, but how will the next person find the link? I went to Python.org and i did not see it on the home page, nor the doc page... and i've been Python-ing for years now! If i can't find the link, how will a noob find it? How much longer are we going to treat the symptoms before we realize that we're dealing with a disease that can be cured? -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Mar 7, 10:47 am, Rick Johnson rantingrickjohn...@gmail.com wrote: That's great Terry, but how will the next person find the link? Why do you have such a low opinion of others that you think they're unable to look up Reporting Bugs in the _documentation_? -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
I actually just tried that, and the results weren't very good. Using the doc's search feature, the Reporting Bugs (and the About these documents) page was significantly down the page (about 2/3 of the way) - not the most obvious result in the pile. All the other searches I could think of either didn't return either of those pages at all, or they were also 1/2-2/3 of the way down the page. The link is also on the main documentation page, but it is, again, near the bottom, making it hidden from many users. Both of them show up just above the bottom of the window with it maximized on my screen. The first of the issues may be difficult to fix, but would likely be fairly useful - that would generally be my first port of call. The second one is more minor as most people will scroll down to see whats farther down, if they go to the main page to find the links. Chris On Wed, Mar 6, 2013 at 5:06 PM, alex23 wuwe...@gmail.com wrote: On Mar 7, 10:47 am, Rick Johnson rantingrickjohn...@gmail.com wrote: That's great Terry, but how will the next person find the link? Why do you have such a low opinion of others that you think they're unable to look up Reporting Bugs in the _documentation_? -- http://mail.python.org/mailman/listinfo/python-list -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, March 6, 2013 7:06:56 PM UTC-6, alex23 wrote: Why do you have such a low opinion of others that you think they're unable to look up Reporting Bugs in the _documentation_? I don't have a low opinion of anybody here. However the fact that this community needs an entry level path for bug/grievance reports is *glaringly* obvious. It would greatly benefit this community by: 1. Removing excess chatter from the bug tracker. We need to keep the tracker folks focused on *real* bugs that can be patched. Not engaged in endless discussions on the semantics of what is a bug and what IS NOT a bug. 2. Removing barriers to reporting bugs/grievances. Remember, if reporting issues is too difficult, people will just give up. Then, the next person who gets slammed with the same problem will go through the same trouble only to produce no results AGAIN. Rinse and repeat! 3. Give us insight as to what aspects of the language/docs are troubling for folks. We need to know where the bottle necks are when learning the language, and since we are experienced, we lack the noob insight to even see the problems. I'll bet $100 you hated writing self as the first argument to each method. But now you've become so accustomed that you could so it in your sleep. That does not validate the asininity of doing such a thing! How can we fix entry-level problems if we DON'T KNOW WHAT THE PROBLEMS ARE! 4. Create a *real* sense of community. By creating a place for people to voice complaints, we are letting them know that Hey, you opinion is important to us, even if you are a total NOOB!. Even if their pet problem is never solved (maybe because it was a misunderstanding all along), they are more likely to get involved more deeply in Python community later on. Heck, maybe they will work their way up to py-dev and rub shoulders with GvR one day, the skys the limit! I have already offered my assistance managing such a list. But i cannot start such a list without wide community support; I cannot start the list without GvR publicly supporting it; I cannot start the list without a prominent link on python.org; because if i do start a list without all these things, i will be wasting my time. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 3/6/2013 7:47 PM, Rick Johnson wrote: On Wednesday, March 6, 2013 5:50:35 PM UTC-6, Terry Reedy wrote: If you find a bug in this documentation or would like to propose an improvement, please send an e-mail to d...@python.org describing the bug and where you found it. If you have a suggestion how to fix it, include that as well. That's great Terry, but how will the next person find the link? The same way I did. Go to http://docs.python.org/3/ (or /2/ and click on Reporting bugs, which takes one to the above and more. I went to Python.org and i did not see it on the home page, nor the doc page... Which doc page? How much longer are we going to treat the symptoms We would VERY MUCH like a system to make it easier for readers to report doc bugs and developers to fix them. No one yet has come up with both a reasonable idea and workable implementation. Here is an idea I just came up with. *Someone* writes javascript that allows the following: Reader using the web version sees a mistake, selects some text with the mistake, right clicks, selects 'Suggest correction', gets a box or form with the selected text, page and location or context info, and a text entry box. Reader enters correction in text box and clicks OK. Message is emailed or posted to python.org. *Someone* writes a python script to process reports by generating a proposed patch for human review. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Thu, 07 Mar 2013 02:28:10 +0100, Chris Kaynor ckay...@zindagigames.com wrote: I actually just tried that, and the results weren't very good. Using the doc's search feature, the Reporting Bugs (and the About these documents) page was significantly down the page (about 2/3 of the way) - not the most obvious result in the pile. All the other searches I could think of either didn't return either of those pages at all, or they were also 1/2-2/3 of the way down the page. Using Google it took me about 3 seconds to find the page. python report doc bug. Works with Bing or DuckDuckGo too. First hit on either engine. The doc's search is ... fine if I search for e. g. 'subprocess.Popen', but near-useless for general searches. The link is also on the main documentation page, but it is, again, near the bottom, making it hidden from many users. Both of them show up just above the bottom of the window with it maximized on my screen. The first of the issues may be difficult to fix, Is it? You'd just have to have an additional search box labeld search whole page with google/bing/whatever (?) but would likely be fairly useful - that would generally be my first port of call. The second one is more minor as most people will scroll down to see whats farther down, if they go to the main page to find the links. Chris On Wed, Mar 6, 2013 at 5:06 PM, alex23 wuwe...@gmail.com wrote: On Mar 7, 10:47 am, Rick Johnson rantingrickjohn...@gmail.com wrote: That's great Terry, but how will the next person find the link? Why do you have such a low opinion of others that you think they're unable to look up Reporting Bugs in the _documentation_? -- http://mail.python.org/mailman/listinfo/python-list -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Mar 7, 11:31 am, Rick Johnson rantingrickjohn...@gmail.com wrote: I don't have a low opinion of anybody here. However the fact that this community needs an entry level path for bug/grievance reports is *glaringly* obvious. Please explain how finding your vanity list would be easier than reading the Python doc's table of contents and clicking on the entry Reporting Bugs. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, March 6, 2013 7:52:59 PM UTC-6, Terry Reedy wrote: How much longer are we going to treat the symptoms We would VERY MUCH like a system to make it easier for readers to report doc bugs and developers to fix them. No one yet has come up with both a reasonable idea and workable implementation. Here is an idea I just came up with. *Someone* writes javascript that allows the following: Reader using the web version sees a mistake, selects some text with the mistake, right clicks, selects 'Suggest correction', gets a box or form with the selected text, page and location or context info, and a text entry box. Reader enters correction in text box and clicks OK. Message is emailed or posted to python.org. YES, YES, YES! This is even better than PyWarts because the user will not need to log onto a forum and then compose a post. In effect, the forum will come to him! I love it! However, there is a dark-side on the opposite side of this mountain. Your idea solves doc related issues, but what about language related issues? I still love your idea, however, i am looking for a holistic approach to solving the issue. *Someone* writes a python script to process reports by generating a proposed patch for human review. Also, i would like to add. That all user submitted reports should be posted in a searchable database somewhere that is public; so we can keep track of which parts of the docs (or language) are creating the highest volume of complaints\bugs. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Thu, Mar 7, 2013 at 12:31 PM, Rick Johnson rantingrickjohn...@gmail.com wrote: We need to know where the bottle necks are when learning the language, and since we are experienced, we lack the noob insight to even see the problems. I'll bet $100 you hated writing self as the first argument to each method. But now you've become so accustomed that you could so it in your sleep. Gambling debts are due within twenty-four hours. Please remit that hundred dollars immediately; I had absolutely no problem with the explicit 'self' argument. Thanks, it's about time I earned some money arguing with you. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, March 6, 2013 8:28:42 PM UTC-6, alex23 wrote: On Mar 7, 11:31 am, Rick Johnson rantingrickjohn...@gmail.com wrote: I don't have a low opinion of anybody here. However the fact that this community needs an entry level path for bug/grievance reports is *glaringly* obvious. Please explain how finding your vanity list would be easier than reading the Python doc's table of contents and clicking on the entry Reporting Bugs. Firstly: It's not a Rick's Vanity List unless my name is on it. I don't expect to be named the BDFL of PyWarts. Heck, i don't even expect to be named at all. GvR DOES NOT need to mention my name. All i am asking is that he show some support for the general *idea* of lowering the bar for bug/grievance reporting. Or at least start by admitting we have a problem. Secondly: The report bugs feature of the doc is more concerned with doc related bugs. I want a holistic approach that will invite ALL Python related issues (docs, language, community, modules, 3rd party modules, etc...) to follow a linear path. There may be better ways of achieving my goals (f.e. Terry proposed a great idea). My point is that we need to lower the bar and try to integrate a linear path that will allow all levels of Python programmers to participate. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Mar 7, 12:57 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: GvR DOES NOT need to mention my name. All i am asking is that he show some support for the general *idea* of lowering the bar for bug/grievance reporting. Or at least start by admitting we have a problem. Your obsession with Guido is tiring. Open source is not a cult of personality. It's about doing what you can where you can when you can to make things better. Insisting that he endorse your ideas is ridiculous. Secondly: The report bugs feature of the doc is more concerned with doc related bugs. It would really help your arguments if you actually spent some time investigating the issues you're ranting against: http://docs.python.org/3/bugs.html Documentation bugs are a brief paragraph at the top of the page, the rest of which addresses bugs with the language standard library. I want a holistic approach that will invite ALL Python related issues (docs, language, community, modules, 3rd party modules, etc...) to follow a linear path. Third party modules will never be handled by the Python bug tracker, nor should they be lumped into the same path; they're the concern of their developers who shouldn't be bound by your desire for a One True Way. Community bugs should be addressed on the python list. My point is that we You keep saying we when you mean other people apart from yourself. If you have ideas for improvement, _then implement them_. The crate.io guys didn't wait for community validation to address what they perceived were issues with PyPI, they rolled up their sleeves and did something about it. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, March 6, 2013 9:12:37 PM UTC-6, alex23 wrote: Your obsession with Guido is tiring. And your false accusations that i am somehow obsessed with GvR have BEEN tiring for quite some time! I am neither passionate for or prejudice against the man. I simple ask that he live up to his job title. Open source is not a cult of personality. It's about doing what you can where you can when you can to make things better. Insisting that he endorse your ideas is ridiculous. Of course insisting that he validate me *personally* would be ridiculous. But i am NOT suggesting that he validate ME, i am suggesting that he do his job. And his job is to oversee the language evolution and maintain a sense of community. Specifically: leading by example. Q: Why even have a python-list if GvR and all the heavies at py-dev never participate in the conversations? By NOT participating they are speaking louder than words. Third party modules will never be handled by the Python bug tracker, nor should they be lumped into the same path; they're the concern of their developers I agree, that was an unfortunate typo. If you have ideas for improvement, _then implement them_. The crate.io guys didn't wait for community validation to address what they perceived were issues with PyPI, they rolled up their sleeves and did something about it. Great, and i commend the contribution. But is yet ANOTHER Python package list going to help anyone? How about 10 or 20 more Python package indexes? Community fragmentation and language forks due to core-dev stubbornness is unfortunate. I would much rather had them contribute to the existing package index instead of creating a new one. Congratulations Alex, your solution of pushing everyone away is working flawlessly -- just don't be surprised when you find yourself cold and alone. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote: On Feb 27, 1:13 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: [...] do you /really/ expect that people have the time to open an issue on the bug tracker? If someone can write a paragraph on their blog or this list complaining about a problem, then yes, they have the time to open an issue on the bug tracker. I've tried twice to register with the bug tracker -- including just before sending this post. Both times I got something like this: Subject: Failed issue tracker submission From: Python tracker roundup-ad...@psf.upfronthosting.co.za Date: Wed, 06 Mar 2013 00:56:44 + An unexpected error occurred during the processing of your message. The tracker administrator is being notified. So, it's not all that easy to report bugs for me, anyway. I'd given up, prior, but reading this thread I thought I'd try one more time. I had wanted to report doc bugs, too, as I used to do copy and line editing. I seem to be able to find typos and such rather easily, but reporting said bugs -- not so easy. Something seems amiss, I'd say. It may be just me, but the point still stands. --Bob Hanson -- Hanson's Heuristic: Ninety-eight percent of what I think I know is bullshit. The rest is crap. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
[Sorry for the double-post -- I somehow had Followup-To set to poster in the first post.] On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote: On Feb 27, 1:13 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: [...] do you /really/ expect that people have the time to open an issue on the bug tracker? If someone can write a paragraph on their blog or this list complaining about a problem, then yes, they have the time to open an issue on the bug tracker. I've tried twice to register with the bug tracker -- including just before sending this post. Both times I got something like this: Subject: Failed issue tracker submission From: Python tracker roundup-ad...@psf.upfronthosting.co.za Date: Wed, 06 Mar 2013 00:56:44 + An unexpected error occurred during the processing of your message. The tracker administrator is being notified. So, it's not all that easy to report bugs for me, anyway. I'd given up, prior, but reading this thread I thought I'd try one more time. I had wanted to report doc bugs, too, as I used to do copy and line editing. I seem to be able to find typos and such rather easily, but reporting said bugs -- not so easy. Something seems amiss, I'd say. It may be just me, but the point still stands. --Bob Hanson -- Hanson's Heuristic: Ninety-eight percent of what I think I know is bullshit. The rest is crap. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
[Sorry for the double-post -- I somehow had Followup-To set to poster in the first post.] On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote: On Feb 27, 1:13 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: [...] do you /really/ expect that people have the time to open an issue on the bug tracker? If someone can write a paragraph on their blog or this list complaining about a problem, then yes, they have the time to open an issue on the bug tracker. I've tried twice to register with the bug tracker -- including just before sending this post. Both times I got something like this: Subject: Failed issue tracker submission From: Python tracker roundup-ad...@psf.upfronthosting.co.za Date: Wed, 06 Mar 2013 00:56:44 + An unexpected error occurred during the processing of your message. The tracker administrator is being notified. So, it's not all that easy to report bugs for me, anyway. I'd given up, prior, but reading this thread I thought I'd try one more time. I had wanted to report doc bugs, too, as I used to do copy and line editing. I seem to be able to find typos and such rather easily, but reporting said bugs -- not so easy. Something seems amiss, I'd say. It may be just me, but the point still stands. --Bob Hanson -- Hanson's Heuristic: Ninety-eight percent of what I think I know is bullshit. The rest is crap. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 06/03/2013 01:43, Bob Hanson wrote: On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote: On Feb 27, 1:13 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: [...] do you /really/ expect that people have the time to open an issue on the bug tracker? If someone can write a paragraph on their blog or this list complaining about a problem, then yes, they have the time to open an issue on the bug tracker. I've tried twice to register with the bug tracker -- including just before sending this post. Both times I got something like this: Subject: Failed issue tracker submission From: Python tracker roundup-ad...@psf.upfronthosting.co.za Date: Wed, 06 Mar 2013 00:56:44 + An unexpected error occurred during the processing of your message. The tracker administrator is being notified. So, it's not all that easy to report bugs for me, anyway. I'd given up, prior, but reading this thread I thought I'd try one more time. I had wanted to report doc bugs, too, as I used to do copy and line editing. I seem to be able to find typos and such rather easily, but reporting said bugs -- not so easy. Something seems amiss, I'd say. It may be just me, but the point still stands. --Bob Hanson You'll be delighted to know that everybody will have to sign a contributor agreement if they're supplying a patch file on the bug tracker, see http://blog.python.org/2013/03/introducing-electronic-contributor.html and http://mail.python.org/pipermail/python-dev/2013-March/124540.html -- Cheers. Mark Lawrence -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Tue, 05 Mar 2013 17:51:36 -0800, Bob Hanson wrote: I've tried twice to register with the bug tracker -- including just before sending this post. Both times I got something like this: Subject: Failed issue tracker submission From: Python tracker roundup-ad...@psf.upfronthosting.co.za Date: Wed, 06 Mar 2013 00:56:44 + An unexpected error occurred during the processing of your message. The tracker administrator is being notified. Works for me. Please try again, and if it still does not work, please email me off-list and I will help you either set up an account or report a tracker bug. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
The OP speaks for himself alone. Python - for such a very young language, and with the documentation and community blogs available at this point - I cannot ask for more. And who needs docs when the python syntax is as good as writing plain english sentence? On Fri, Mar 1, 2013 at 9:06 PM, Jean-Michel Pichavant jeanmic...@sequans.com wrote: [snip hostile replies] It's somehow funny to read such posts on a thread about someone complaining about the community python being hostile. I think we should really try to resist the urge of answering trolls because no matter how many times we slap them, they'll stay trolls and probably get even bigger. Instead, we take revenge by helping someone asking us to do his homework and show the world how merciful the python community is. JM -- IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you. -- http://mail.python.org/mailman/listinfo/python-list -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
[snip hostile replies] It's somehow funny to read such posts on a thread about someone complaining about the community python being hostile. I think we should really try to resist the urge of answering trolls because no matter how many times we slap them, they'll stay trolls and probably get even bigger. Instead, we take revenge by helping someone asking us to do his homework and show the world how merciful the python community is. JM -- IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, February 27, 2013 11:57:05 PM UTC-6, alex23 wrote: On Feb 28, 2:53 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: On Wednesday, February 27, 2013 10:18:46 PM UTC-6, alex23 wrote: [...] * Do you care about the evolution of Python or just give it lip service? I don't see any problems with how Python is developing now. Then again, I am pretty busy using it to write code. So go write your code and stop trying to stymie the attempts of others who wish to improve Python. Your participation is NOT compulsory! * Do you have an ideas for the name of a Python grievance list? http://bugs.python.org/ Well thanks for actually answering a question directly, but we must dig deeper. Deciding the _name_ of a list is just one small detail, the most important question is this: Q: Do you feel that the bug tracker should be a place where users discuss grievances that distract volunteers from fixing actual bugs? I'm of the opinion that such discussions are more suited for an entry-level grievance list (such as: PyWarts). * What are your opinions of the state of both Tkinter and IDLE? Are you proud of these modules/packages? I don't use them, So again, why bother to stymie the attempts of others who DO use them? Crawl back under your rock and write some code. ...nor do I need to feel pride about any part of the Python standard library. Either something is useful to me or not. That's a fairly selfish outlook Alex. Okay, maybe you don't care about the state of Python's stdlib, fine, but other people do. How does flinging poo on these people help anyone? But more importantly how does flinging poo reflect on your image in this community? * Why do you support Guido's continued reign of silence? Why do you inject hyperbole into everything you write? The question is quite valid and your are diverting again! * But most importantly, do you not want the community/ language to evolve or remain static? I already answered that above. [...] Can you provide a link to your improved tkinter package on PyPI? No, because my awesome re-write of Tkinter does not live at PyPI. Where is your draft PEP for its inclusion in the standard library? I have not written a PEP on the subject. Are you suggesting that if i don't write a PEP my proposal is dead in the water? If so, this is exactly the kind of barriers that keep Python's stdlib in such a atrocious state! What if i'm a horrible writer and a genius code artist? If the community judges the value of source code based on the rhetoric of a document describing the source code, then they are basing their judgments on folly. What happens if i am a seasoned programmer but English is my second language? It is my opinion that PEP are great, but they should not be compulsory to having your ideas seriously considered by the community. A great idea is a great idea, no matter how much fluff you add to it. Likewise, a poor idea is a poor idea, and no amount of fluff could ever make it better. In this sense, PEP are a waste of valuable time. And let's not forget the irony here; the default reply for documentation issues is for the user to read the effing source!. Hmm, so *you* and others feel that reading source is compulsory for those *without* the ability to comprehend the source, and a waste of time for those *with* the ability to read source? Is this not the definition of hipocracy Alex? I have a feeling there is a bit of malevolence in there also. Alex, your in ability to understand the asinine barriers a contributor to this community must negotiate is leading me to believe you have _insidious_ intentions. How is RickPython proceeding? My personal Python fork is of no concern to this community, or this mailing list; STAY ON TOPIC! What is your opinion on anything Python related Alex? My biggest regret re Python is that you found it more appealing than Ruby and we got saddled with you instead. Ahh, and this little off-hand statement uncovers the hidden truth. Regardless of your personal feeling of me, your underlying hatred of Python is *glaringly* apparent! You responded to a request for advice on learning how to handle complex projects with: Before you decide to start participating in outside projects may we have a list of some of the software you've written for yourself? (With all due respect) I very seriously doubt that someone with only a few months of programming experience is ready for the real world. The OP of that thread asked for advice on large projects that we might recommend. I tend to prefer giving people good advice and only guessing when i have not other choice. In order to offer good advice i need to know first how experienced the OP is with programming (not only python, but all languages). The only hint the OP offered was this: # Quote #
Re: Do you feel bad because of the Python docs?
On Fri, Mar 1, 2013 at 5:28 AM, Rick Johnson rantingrickjohn...@gmail.com wrote: Q: Do you feel that the bug tracker should be a place where users discuss grievances that distract volunteers from fixing actual bugs? So you admit that discussion of your whining about perceived grievances would distract busy people from doing useful things to and with Python... and yet you demand GvR's *personal* involvement. I think you grossly misunderstand the position of BDFL. It's servant to all, but not grovelling, boot-licking sap with no life who spends all day dealing with idiots. A subtle difference, I'm sure, and I can understand how someone of your intellect could fail to recognize it. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Mar 1, 4:28 am, Rick Johnson rantingrickjohn...@gmail.com wrote: And by the way Alex, you are free to put *your* face into the conversation anytime you like. You're such a little fascist. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 26/02/2013 12:54, Steven D'Aprano wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ It is valuable to contrast and compare the PHP and Python docs: http://php.net/manual/en/index.php http://www.python.org/doc/ There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. But should we feel bad about Python's docs? I don't think that either the Python documentation or community is as bad as JoePie91 suggests. (Well, I won't speak for the people on Freenode's #python. It took me approximately three minutes to be banned from there, with no warning or explanation.) Another response to the blog post, by one of the core developers: http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html Not really when we've got world leading experts to help us out http://xahlee.info/perl-python/python_doc.html :) * sys.maxint -- Cheers. Mark Lawrence -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
Steven D'Aprano steve+comp.lang.python at pearwood.info writes: It is valuable to contrast and compare the PHP and Python docs: http://php.net/manual/en/index.php http://www.python.org/doc/ I suppose you should compare it with http://docs.python.org/3/ instead. There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. My (probably outdated) experience with the PHP docs is that they are very succinct and don't document failure cases or behavioral details at all. Sure, if you only care about the big picture, they are good enough. Regards Antoine. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
Mitya Sirenef msirenef at lightbird.net writes: I think the issue with python documentation is that it ignores the 95/5 rule: 95% of people who land on a module's page are only looking for 5% of its information. The 95/5 rule is generally a fallacy which ignores that the 5% which the readers are expecting to learn about is not the same 5% from reader to reader. (*) Which means that in the end you would really want a diversity of HOWTOs targeted at different usages of the stdlib. But it is a lot of work to write *and* maintain. (*) cf. http://www.joelonsoftware.com/items/2006/12/09.html Regards Antoine. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 02/27/2013 08:22 AM, Antoine Pitrou wrote: Mitya Sirenef msirenef at lightbird.net writes: I think the issue with python documentation is that it ignores the 95/5 rule: 95% of people who land on a module's page are only looking for 5% of its information. The 95/5 rule is generally a fallacy which ignores that the 5% which the readers are expecting to learn about is not the same 5% from reader to reader. (*) Which means that in the end you would really want a diversity of HOWTOs targeted at different usages of the stdlib. But it is a lot of work to write *and* maintain. (*) cf. http://www.joelonsoftware.com/items/2006/12/09.html Regards Antoine. It would be absurd on my part to claim that they're precisely the same 5%. But then again, they don't have to be. Consider that some topics are covered in the official tutorial while others are omitted -- the authors of the tutorial were following the same rough 95/5 concept and the idea that some readers will find stuff they don't need in the tutorial while at the same time not finding some of what they DO need -- did not stop them from writing the tutorial, nor does it mean the tutorial is not useful. -m -- Lark's Tongue Guide to Python: http://lightbird.net/larks/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, February 27, 2013 7:22:44 AM UTC-6, Antoine Pitrou wrote: Which means that in the end you would really want a diversity of HOWTOs targeted at different usages of the stdlib. But it is a lot of work to write *and* maintain. So instead we maintain a simple, albeit broken, doc that experienced pythonista's prefer to read, whilst newbies loath? Is not the *target* audience noobs? -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 02/26/2013 05:54 AM, Steven D'Aprano wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ It is valuable to contrast and compare the PHP and Python docs: tl;dr? tb I haven't used PHP or its documentation so I can't compare it to Python's. I have used Python's documentation and can say I agree with many of the criticisms made by JoePie91. One of the problems with fixing the Python reference docs (by which I mean primarily the Language and Library References) it that there is no common agreement about what a good reference should be. In the Python development community that controls the overall structure and contents of the Python documentation, there seems to be strong minimalist streak. It often seems like the documentation is the product of a contest to find the minimum number of words to describe something and still be able to defend it as correct. Any documentation must be written with a target audience in mind and IMO the audience for the Python reference docs should be programmers familiar with one or two procedural or OO languages at an intermediate level. (Obviously different sections of documentation can modify this. Later documentation will assume knowledge of basic concepts like Python objects, argument passing and assignment semantics and so forth that were presented earlier, and documentation for specialized problem domain modules, eg an SMTP module, would assume some knowledge of email, smtp and networking.) As JoePie91 pointed out, reference material should describe its subject matter completely and accurately. Once documentation has archived that minimum bar of viability, its quality is determined by how effectively it transfers that information to the reader. I distinguish reference from tutorial material in that the former is optimized for looking up information and presenting it concisely, the latter for presenting (quite possibly the same) information in a linear fashion with no forward references and presenting it verbosely and experientially. I distinguish a language reference from a language standard in that the audience for the latter are language implementors rather than users. I would describe a reference document for those already competent with Python and as a big cheat-sheet. A frequent failing of the Python docs is just plain poor writing. When explaining something, start with a description of what the something is, does, etc, in a form understandable by the target audience. Is there anyone who can understand what the very useful collections.defaultdict does without multiple rereadings? According to its docs, it returns a new dictionary-like object. That is underspecified -- many things return dictionary-like objects. It continues it overrides one method and adds one writable instance variable. OK, but WTF does it *do*?! It then goes on to describe its use which one has to understand without an overarching context and then reason backwards to eventually figure out that it is a dict that provides for user-specified behavior when accessed with a key that doesn't exist [*1] Important quality enablers are good tables of contents, indexes, glossaries, cross references and examples. Examples should be used to illustrate a textual description and never used as a substitute for textual descriptions. Cross references are particularly important in tying together related material that is found in disparate doc locations. For example, information on Python's + operator is found in: Lang: 2.5. Operators Lang: 3.3.7. Emulating numeric types Lang: 6.5. Unary arithmetic and bitwise operations Lang: 6.6. Binary arithmetic operations Lang: 6.15. Summary (mislabeled, actually operator precedence) Lib: 4.4. Numeric Types Lib: 4.6.1. Common Sequence Operations Lib: 10.3. operator and probably other places I did not think to look. The index is not much help in tying any of these together: add - Lib: 2.5 +- Lib: 4.4 plus - Lang: 6.5 There are also more obscure uses that should be findable such as in float hex strings (4.4.3. Additional Methods on Float) Cross references to similar information can help cover for failings in the index -- if you can find some similar function or concept, there is (or should be) a good chance of a cross- reference to what you really wanted. Good documentation will anticipate the questions a reader will have and answer them. Rebuttals to common responses to criticism of Python docs: Python docs are already good * Criticisms of Python's docs pop up on the Python maillist and blogs with regularity. * Many people confuse usable, i've learned to use despite, look impressive, etc with good. Google / blogs / stackoverflow / reddit, etc can provide better *
Re: Do you feel bad because of the Python docs?
On Feb 27, 1:13 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: Terry (with all due respect), do you /really/ expect that people have the time to open an issue on the bug tracker? If someone can write a paragraph on their blog or this list complaining about a problem, then yes, they have the time to open an issue on the bug tracker. This is the price of using open source software: you give back. You don't get to say I don't have the time for this, *someone else* fix it. Who do you expect to give up *their* time to solve *your* issues? Ranting on public forums is nothing but posturing at best, and at worst an attempt to blackmail-by-shame people into doing something for you. Same goes for calls for the community to fix things. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wed, 27 Feb 2013 15:20:04 -0800, rurpy wrote: As JoePie91 pointed out, reference material should describe its subject matter completely and accurately. Once documentation has archived that minimum bar of viability, its quality is determined by how effectively it transfers that information to the reader. Those priorities are backwards. Badly written reference materials that are ineffective at transferring information is potentially useless, no matter how complete and accurate, and there's often not much you can do to make it better written other than throwing it away and starting again. But well-written reference material that is incomplete can be incrementally added to, eventually making it complete. If anyone thinks that being complete is more important than being readable, let me point out that the Python source code is a 100% complete and accurate reference to the behaviour of Python. So we're done, yes? No of course not. [...] Documentation is the ultimate authority for what it is *supposed* to do. Incorrect. If that were true, then there could never be a documentation bug. Documentation can be buggy, just as software can be buggy. If function f() is documented as doing X, but actually does Y, which one is correct? In general there is no way to tell. In practice, the ultimate authority is the consensus (if any!) of the people who write the software. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 02/26/2013 11:43 AM, Terry Reedy wrote: On 2/26/2013 7:54 AM, Steven D'Aprano wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ In which JoePie91 writes: ...the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen... To me, this is a lying troll rant worth less than most of RantingRick's posts. Rather making his point, aren't you? [...] -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
In article 54967758-e84c-4b9c-a09c-10fbdbec2...@googlegroups.com, Rick Johnson rantingrickjohn...@gmail.com wrote: do you /really/ expect that people have the time to open an issue on the bug tracker? There's a certain amount of socialism involved in OSS. From each according to his ability, really is the way it works. If your ability is that you've discovered that the documentation isn't as good as it should be, you owe the project a few minutes of your time to create a ticket describing the problem (and, even better, suggesting how it could be improved). Looking at my bugs.python.org activity, I see I've opened 30 bugs over the past 9-1/2 years. Of those, 16 were explicitly against the docs, and a few more were of the I'm not sure if this is a docs bug or a code bug, but it doesn't do what it says it does variety. Do you really think that everyone who uses python even knows about the bug tracker? Everybody? No. But, anybody who uses OSS should understand that any non-trivial project has a bug tracker. And even if they don't know where it is, they should be capable of typing python bug tracker into a search engine and finding it. Do you really think that people will believe that their opinion is worthy of placing on the bug tracker? In my experience, it's far more likely for people to over-estimate the important of their own opinion than to under-estimate it :-) -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 28/02/2013 01:17, ru...@yahoo.com wrote: On 02/26/2013 11:43 AM, Terry Reedy wrote: On 2/26/2013 7:54 AM, Steven D'Aprano wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ In which JoePie91 writes: ...the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen... To me, this is a lying troll rant worth less than most of RantingRick's posts. Rather making his point, aren't you? [...] No. -- Cheers. Mark Lawrence -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, February 27, 2013 5:25:25 PM UTC-6, alex23 wrote: Ranting on public forums is nothing but posturing at best, and at worst an attempt to blackmail-by-shame people into doing something for you. Same goes for calls for the community to fix things. What you call ranting is most times people venting frustrations BECAUSE they want to help, but nobody is allowing them to be a contributing member of the community. When someone tries to offer help, in the form of constructive criticism, and then somebody snaps at them, they then loose the will to help. I myself would love to contribute my quite awesome re-write of the Tkinter GUI library, but due to the friction i've encountered on this list, i am resigned to keep it to myself (at least for the time being). Which is sad because python (and python programmers) could greatly benefit from a polished Tkinter. Alex i can assure you, there DOES exist a very harsh attitude to outside opinions within this community. Case in point: Why should ANYBODY need to voice Python problems on various blogs around the web? I think it would be in the interest of the Python community to have these opinions voiced here, on the list, for all to discuss. This is why i will AGAIN mention my PyWarts list (Hypothetical at this point). We need an official place for the many problems of Python to be discussed in a fair and open manner. A place that will be open to noobs and frequented by pythonisitas (including the BDFL himself!) Path of a Python Issue 1. All perceived problems with python get voiced on the PyWarts list 2. After considerable discussion, and if we can widdle the problem down to a tangible bug, then a bug gets opened on the tracker. 3. Hopefully the bug will be resolved and closed ASAP. This is a linear path of inclusion that will prompt people to participate. You and i both know we need more people working at the tracker, and there are many who want to participate, but they will never participate at the bug tracker level when they get nothing but friction at the python-list level. We all need to tone down the hostility and lower the bar for those who wish to help. Neither this community nor this language can survive without a steady adoption of new members. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
In article 287852cd-09ee-4768-9591-c1f31fe04...@googlegroups.com, Rick Johnson rantingrickjohn...@gmail.com wrote: When someone tries to offer help, in the form of constructive criticism, and then somebody snaps at them, they then loose the will to help. I myself would love to contribute my quite awesome re-write of the Tkinter GUI library, but due to the friction i've encountered on this list, i am resigned to keep it to myself (at least for the time being). Which is sad because python (and python programmers) could greatly benefit from a polished Tkinter. So, put it on github (or whatever), and announce its availability. If the Tkinter user community finds it valuable, they'll use it. There's plenty of third party packages that are better than what's packaged with the core system (requests vs urllib, for example). -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2/27/2013 8:17 PM, ru...@yahoo.com wrote: On 02/26/2013 11:43 AM, Terry Reedy wrote: In which JoePie91 writes: ...the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen... To me, this is a lying troll rant worth less than most of RantingRick's posts. Rather making his point, aren't you? Not at all. Over the past 15 years I have make 1000s of polite helpful responses to perhaps 100s of different people. Others have done much the same. The fact that I am hostile to and occasionally make an exception to not responding to lying troll rants does not at all prove his lie. Indeed, Joe did not post here, and I was not speaking to him. I intended my complete post to be overall helpful to people who do read here. If Joe ever does post a polite question here, I hope and expect he would get a polite response. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
I just completed my first Python app for public consumption, and I was learning as I was coding. I've played on the outskirts of the language for a few years, but until this project I'd never really immersed myself in it. I ended up being confused a lot. So, I DO have some relevant thoughts: 1. The Python official documentation is not great, but it's not bad either. Some of it seems outdated, some of it is a bit hard to parse, some of it assumes more background knowledge on the part of the reader than is justified. Somebody mentioned the Django documentation. I've looked at it a bit, and it's *very* nice. I do think that the PSF could take some clues from its style and approach. But those are pretty minor gripes. I've learned a lot from referencing the documentation, and its still my first go-to source when I'm stuck. 2. The Python Community: Jopie91 wrote I will no doubt piss off quite a few people with this statement, but the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen – and with that I am not just referring to #python on Freenode, but to communities with a dense population of Python developers in general. This point actually consists of several separate attitudes and issues. There, I'd have to say he's very, very wrong. When I have on occasion asked questions on this group I've never been flamed, and I've always had people give me thoughtful answers that obviously took some effort to compose. My most recent question here concerned something that was thought to be a bug, but was due more to my own unfamiliarity with the material combined with what I'd suggest really was some ambiguity on the part of the documentation. Nevertheless, even with the misunderstandings, my questions were treated respectfully, and that's all I ask. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Thu, Feb 28, 2013 at 1:05 PM, Rick Johnson rantingrickjohn...@gmail.com wrote: This is why i will AGAIN mention my PyWarts list (Hypothetical at this point). We need an official place for the many problems of Python to be discussed in a fair and open manner. A place that will be open to noobs and frequented by pythonisitas (including the BDFL himself!) Path of a Python Issue 1. All perceived problems with python get voiced on the PyWarts list 2. After considerable discussion, and if we can widdle the problem down to a tangible bug, then a bug gets opened on the tracker. 3. Hopefully the bug will be resolved and closed ASAP. Go start the list. When you get something that's worth posting, go post it on the tracker. And if you post something with an actual patch, then maybe it'll be accepted. Why are you demanding that busy people attend to you? You are effectively demanding that Guido, who has a full-time job as well as being head of a large project, should - without compensation - read and actively respond to every one of your whiny posts. That is simply not going to happen unless he *wants to*. It's up to you to make it worth his while, or at least interesting. That's how things work. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, February 27, 2013 8:44:08 PM UTC-6, Chris Angelico wrote: On Thu, Feb 28, 2013 at 1:05 PM, Rick Johnson wrote: This is why i will AGAIN mention my PyWarts list (Hypothetical at this point). We need an official place for the many problems of Python to be discussed in a fair and open manner. A place that will be open to noobs and frequented by pythonisitas (including the BDFL himself!) [...] Go start the list. But with that statement you keep missing the point. We DON'T need yet another list on yet another corner of the web. What we DO need is a list that is local to the community. Are you asking me to start a pywarts usenet list? Does the community want it to be titled PyWarts? How about showing me that you are really interested by offering some name ideas. I am quite partial to PyWarts because i think the name is catchy, but i am open to outside ideas, have at it! When you get something that's worth posting, go post it on the tracker. And if you post something with an actual patch, then maybe it'll be accepted. Yes, that's step two. First step: discussion to find the definition of the bug, second step: open a bug report. Having people voicing opinions on the tracker is diverting the time and energy of the good people who volunteer there. We need to move the discussion somewhere else (PyWarts) Why are you demanding that busy people attend to you? You are effectively demanding that Guido, who has a full-time job as well as being head of a large project, should - without compensation - read and actively respond to every one of your whiny posts. I understand the responsibilities that Guido is tasked, and i do not expect him to answer frivolous questions on the list. What i DO expect is that he at minimum publicly support the following: 1. Guido needs to wield his power by announcing (politely) that the community should be more open to outside opinions and methods of solving problems. This is the most important step and the start of a recovery process. 2. Guido should also announce that in order to achieve this goal, we need a very public and very intuitive path of solving Python issues. This path starts at a list for sharing Python related greivances (call it PyWarts if you like) , which HOPEFULLY he will at least make an attempt to visit from time to time. This list (and this path) needs to be mentioned quite prominately on the python.org website (which itself needs quite a bit of polishing!) GvR has not even shown his face on python-list list for around a decade or more. He only posts at py-ideas (that i know of). This is why the community is in such disarray. It is paramount that he make some public appearance and speak of his dreams for the future. How can GvR go and declare himself a BDFL and then sail off into the sunset to his little island paridise of py-ideas without ever giving validity to his people and his creation? If does not want to lead anymore, fine! Say so. If he does, fine! Make an announcment! That is simply not going to happen unless he *wants to*. It's up to you to make it worth his while, or at least interesting. That's how things work. All i ask is for Guido to lead. That's all. He is the only person in this whole damn community who has the influence to speak and have people listen. If he will publicly endorse some good will within the community, and admit that we desperately need a streamed-lined and linear path for solving python's many problems, i can guarantee that we will see a great influx of really smart people. I myself will commit every second i can to help move along the evolution. I also wish he would speak publicly about the stale nature of Tkinter and IDLE. Allowing these two modules to become so outdated is really tarnishing the image of Python's stdlib. Whether you think the modules should be in the stdlib or not, is *not* the question. They are there, so we must try to improve them. Python is a great language, but we need diverse ideas to keep the cogs of evolution turning. Guido can start the ball rolling 10 minutes from now, all it will take is for him to make a public announcement... -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, February 27, 2013 7:43:58 PM UTC-8, Rick Johnson wrote: Python is a great language, but we need diverse ideas to keep the cogs of evolution turning. Guido can start the ball rolling 10 minutes from now, all it will take is for him to make a public announcement... Geez, dude, let the man get some sleep! -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Feb 28, 12:05 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: On Wednesday, February 27, 2013 5:25:25 PM UTC-6, alex23 wrote: Ranting on public forums is nothing but posturing at best, and at worst an attempt to blackmail-by-shame people into doing something for you. Same goes for calls for the community to fix things. What you call ranting is most times people venting frustrations BECAUSE they want to help, but nobody is allowing them to be a contributing member of the community. You claim that no one has time to write a bug report. I point out that if they can spend the time ranting about the bug, then they have the time. You then proceed to try and reframe the discussion to something else entirely. Venting frustrations isn't contributing. If someone is confused about how to contribute, they could just *ask*, as people _regularly_ do here, and are always given reasonable direction how to do so. When someone tries to offer help, in the form of constructive criticism, and then somebody snaps at them, they then loose the will to help. I myself would love to contribute my quite awesome re-write of the Tkinter GUI library, but due to the friction i've encountered on this list, i am resigned to keep it to myself (at least for the time being). Which is sad because python (and python programmers) could greatly benefit from a polished Tkinter. Insisting your personal project is shoved into the standard library isn't helping. Write a PEP. Put the code up on PyPI. There's a well- established path for progressing code from look what I done make! into something that is considered part of Python. Alex i can assure you, there DOES exist a very harsh attitude to outside opinions within this community. Don't extend this list's reaction to you and your particular blend of idiocy to the general response to opinions. Case in point: Why should ANYBODY need to voice Python problems on various blogs around the web? The two main reasons seem to be: vanity, and an unwillingness to listen to criticism. This is why i will AGAIN mention my PyWarts list (Hypothetical at this point). Hypothetical sums up pretty much all of your supposed contributions to date. We need an official place for the many problems of Python to be discussed in a fair and open manner. A place that will be open to noobs and frequented by pythonisitas (including the BDFL himself!) Starting a new forum just fragments the discussion even further. Path of a Python Issue 1. All perceived problems with python get voiced on the PyWarts list 2. After considerable discussion, and if we can widdle the problem down to a tangible bug, then a bug gets opened on the tracker. 3. Hopefully the bug will be resolved and closed ASAP. Ah, so it's your way or no way, yet again. THERE ALREADY EXISTS A PATH FOR DEALING WITH ISSUES. This is a linear path of inclusion that will prompt people to participate. Right, until someone doesn't get the response they want and they agitate for this to happen on Stackoverflow, or IRC, or their brand new forum they've set up. You're not the first person to want to impose your own brand of tyranny on the process. You and i both know we need more people working at the tracker No one is going to be working at the tracker, because no one is *paid* to do such work. People can participate by contributing, or they can choose not to. The latter should also STFU if they're not willing to contribute, but this seems to be a position you're unable or unwilling to understand. Neither this community nor this language can survive without a steady adoption of new members. The current process is not doing anything like the damage to the uptake of Python that you constantly claim it is, but you do love your hyperbole. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Feb 28, 1:43 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: Guido can start the ball rolling 10 minutes from now, all it will take is for him to make a public announcement... Can you please stop this *constant* insistence that Guido talk to you / do what you think is important? It's pointless posturing and empty rhetoric and we've had to put up with it for *years* now. The man has a job and at least one side project that is clearly of far more interest importance to him than jumping through hoops for one incessant whiner. Stop being so damn arrogant and insulting. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wednesday, February 27, 2013 10:18:46 PM UTC-6, alex23 wrote: You claim that no one has time to write a bug report. I point out that if they can spend the time ranting about the bug, then they have the time. And i would like to point out that all your nay-saying and condemnations are taking some valuable time also. Time that could be better spent finding new ways for our new friends to contribute. * Do you care about the evolution of Python or just give it lip service? * Do you have an ideas for the name of a Python grievance list? * What are your opinions of the state of both Tkinter and IDLE? Are you proud of these modules/packages? * Why do you support Guido's continued reign of silence? * But most importantly, do you not want the community/language to evolve or remain static? What is your opinion on anything Python related Alex? All i've heard from you is negativity, condemnation, and insults -- with exception of your statements about the GG's interface the other day, all your other posts have been nothing but lectures to myself and other concerned Python uses. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
Python has a nice Tutorial for beginners. It is an integral part of the doc set. To ignore that (and the indexes) in discussing the usability of Python docs by beginners is to lie. (If beginners who actually read the tutorial have problems with particular paragraphs, improvements can be and have been made.) I never thought about the quality of the Python docs until reading these posts. I started with Python by reading the tutorial and browsing the module pages and have reached some level of competency. I suppose the module pages could stand to have more examples, but as Chris Angelico says this list should be considered part of the documentation, in which case the documents plus this list effectively give me any example I am wanting. I am very grateful to those who have given their time writing the existing documentation, answering questions on this list, and of course writing the language! Python has allowed me to be more successful at my job than the other languages I considered. The lazy and workable approach is to read the module documentation, make a reasonable effort, follow http://www.catb.org/esr/faqs/smart-questions.html, and voilà. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Thu, Feb 28, 2013 at 3:59 PM, Jason Friedman jsf80...@gmail.com wrote: The lazy and workable approach is to read the module documentation, make a reasonable effort, follow http://www.catb.org/esr/faqs/smart-questions.html, and voilà. The Force is strong with this one. If only others would follow this lazy approach... ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 02/27/2013 06:05 PM, Steven D'Aprano wrote: On Wed, 27 Feb 2013 15:20:04 -0800, rurpy wrote: As JoePie91 pointed out, reference material should describe its subject matter completely and accurately. Once documentation has archived that minimum bar of viability, its quality is determined by how effectively it transfers that information to the reader. Those priorities are backwards. Badly written reference materials that are ineffective at transferring information is potentially useless, no matter how complete and accurate, and there's often not much you can do to make it better written other than throwing it away and starting again. Why assume useless? The claim is that much of the current Python documentation is badly written but it is hardly useless. Is it even possible to be complete and accurate and totally useless at the same time? But well-written reference material that is incomplete can be incrementally added to, eventually making it complete. And badly written documentation can be incrementally rewritten so I don't see your point. If you going to start with the premise of docs so badly written they are *totally* useless then start with an equally extreme incompleteness premise: there is no documentation at all (including source code if you want to consider that, documentation). If anyone thinks that being complete is more important than being readable, let me point out that the Python source code is a 100% complete and accurate reference to the behaviour of Python. It may be a complete and accurate if poorly readable reference for those who already know Python and C well (and Java and C#/.net if you want to cover Python generally) but the presumed target audience of the documentation does not necessarily know them. And since you're claiming that readable is more important than complete and accurate, ask yourself which *you* would prefer if you could have only one: readable but incomplete and inaccurate docs or the poorly readable but complete and accurate source code? So we're done, yes? How so? You have source code that is not useful for the intended audience of the documentation and no documentation. No of course not. Right. Perhaps a better way to look at it than I (or you) stated is to consider accuracy and completeness very important qualities of reference documentation, as is of course the writing quality. [...] Documentation is the ultimate authority for what it is *supposed* to do. Incorrect. If that were true, then there could never be a documentation bug. Documentation can be buggy, just as software can be buggy. If function f() is documented as doing X, but actually does Y, which one is correct? In general there is no way to tell. In practice, the ultimate authority is the consensus (if any!) of the people who write the software. Correct documentation is the ultimate authority for what it is supposed to do. In context, that was in contrast to the oft-recommended technique of seeing what the software does without reference to the documentation. I take your point that when behavior and documentation disagree, it may not be immediately clear which is at fault but without reference to the documentation you will never even notice the discrepancy. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Feb 28, 2:53 pm, Rick Johnson rantingrickjohn...@gmail.com wrote: On Wednesday, February 27, 2013 10:18:46 PM UTC-6, alex23 wrote: You claim that no one has time to write a bug report. I point out that if they can spend the time ranting about the bug, then they have the time. And i would like to point out that all your nay-saying and condemnations are taking some valuable time also. Time that could be better spent finding new ways for our new friends to contribute. This is a false conclusion. Why would I spend time doing this when I don't believe it's necessary? * Do you care about the evolution of Python or just give it lip service? I don't see any problems with how Python is developing now. Then again, I am pretty busy using it to write code. * Do you have an ideas for the name of a Python grievance list? http://bugs.python.org/ * What are your opinions of the state of both Tkinter and IDLE? Are you proud of these modules/packages? I don't use them, nor do I need to feel pride about any part of the Python standard library. Either something is useful to me or not. * Why do you support Guido's continued reign of silence? Why do you inject hyperbole into everything you write? * But most importantly, do you not want the community/language to evolve or remain static? I already answered that above. You, on the other hand, constantly dodge any direct questions or criticisms. Can you provide a link to your improved tkinter package on PyPI? Where is your draft PEP for its inclusion in the standard library? How is RickPython proceeding? What is your opinion on anything Python related Alex? My biggest opinion is that you're a ridiculous little blowhard that this community would be better off without. My biggest regret re Python is that you found it more appealing than Ruby and we got saddled with you instead. Other than that, I use it daily to *get real work done*. What do you do with it other than use it as a soapbox for your ego? All i've heard from you is negativity, condemnation, and insults -- with exception of your statements about the GG's interface the other day, all your other posts have been nothing but lectures to myself and other concerned Python uses. And here you descend into slander. I condemn *you* because you're a contemptible twit with delusions of grandeur. I lecture *you* because you'e particularly slow and dim-witted. As for other concerned Python uses, the last few threads we've both posted in I've provided pragmatic advice, if not explicit code samples, while you have done your usual posturing and grandiose bulshytt. You responded to a request for advice on learning how to handle complex projects with: Before you decide to start participating in outside projects may we have a list of some of the software you've written for yourself? (With all due respect) I very seriously doubt that someone with only a few months of programming experience is ready for the real world. And you have the audacity to claim that I'm the one lecturing other people... Who do you think you are, the Python-participation police? -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Thu, Feb 28, 2013 at 4:57 PM, alex23 wuwe...@gmail.com wrote: My biggest regret re Python is that [Ranting Rick] found it more appealing than Ruby and we got saddled with [him] instead. Having used Ruby a little this past couple of weeks (trying to install a Rails application), I fully understand Rick's preference for Python; it just proves that he wants to use a language that's actually ready to use. In discussion with my brother about the problems I'd been having with Ruby, he summed up the status in one pithy phrase: Critical lack of polish. Setting up Ruby + Rails + Spree + all the other gems that those three require, instead of being a fairly simple half-hour job, took me over a day. The main issue is that Ruby functions like a niche language, but is trying to be mainstream. Installing a gem requires that code be compiled, and sometimes that code doesn't compile and I need to fetch some development libraries. That's something I'm quite capable of, as a Linux-based developer, but it's not a job for a systems administrator. How are Ruby-based sites supposed to be deployed? Additionally, there are a number of critical-yet-minor problems. The standard way to invoke Rails is 'rails server' which invokes WEBrick on port 3000. You can change that port, but to use one =1024, you have to be root... and there's no way to have it drop privileges afterwards. So a Ruby on Rails system, accessible on port 80, will have to run everything as root. No thanks. Alternatively, you can set up firewall rules to redirect port 80 to port 3000... or have an Apache load-balancing proxy... or, my personal favorite, set up an SSH tunnel to localhost. All this because there's no standard way to drop privileges after binding (nor a standard way to accept a socket passed from another process, and listen on that - which is possible with Ruby, just not conventional). So, yeah. We're stuck with Rick because we have the better language+library. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Do you feel bad because of the Python docs?
One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ It is valuable to contrast and compare the PHP and Python docs: http://php.net/manual/en/index.php http://www.python.org/doc/ There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. But should we feel bad about Python's docs? I don't think that either the Python documentation or community is as bad as JoePie91 suggests. (Well, I won't speak for the people on Freenode's #python. It took me approximately three minutes to be banned from there, with no warning or explanation.) Another response to the blog post, by one of the core developers: http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Tue, Feb 26, 2013 at 11:54 PM, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ It is valuable to contrast and compare the PHP and Python docs: http://php.net/manual/en/index.php http://www.python.org/doc/ There are some issues with the Googleability of the Python docs at the moment. It's much easier to find the official page of PHP's docs than Python's. Trouble is, the official page of PHP docs is a lot less helpful... like he says, it's in some cases flat-out wrong. And then you go read the comments underneath in the hope of learning what you need to know... and you find a pile of junk even worse than the main docs, but with the occasional useful gem so you can't dismiss it out of hand. (But it's buried among loads of code whose primary purpose is to explain why there's so much bad PHP code out there.) His experiment (name all the possible error conditions) is one that I guarantee you will fail in EVERY language. Even in Java, where a method has to declare every exception it might throw, makes an exception (if you'll excuse the pun) for runtime errors... such as division by zero. So if I write a function that takes two arguments, divides one by the other, and adds three, then I don't need to declare that it might bomb if you give it zero and zero. Will it be in the docs? Unlikely. The lack of examples is a valid concern. However, PHP isn't actually that much better, because the prolific examples don't always help. Examples are no panacea. Final point: NO-ONE IS FIXING THIS. I wonder how many docs patches he's submitted, how many newbies he's courteously and competently assisted. The complaints about the community definitely do not apply to python-list. So I'd say that's a fairly good fallback: if you can't find what you need in the docs, and you've made a genuine effort to do so, ask on c.l.p/p-l and you'll likely get a response within a day - sometimes within the hour. (If Giacomo says he will respond within the hour, he will respond... within the hour!) tl;dr: Nothing's perfect but it ain't as bad as all tharrt. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
In article mailman.2541.1361884843.2939.python-l...@python.org, Chris Angelico ros...@gmail.com wrote: There are some issues with the Googleability of the Python docs at the moment. It's much easier to find the official page of PHP's docs than Python's. Trouble is, the official page of PHP docs is a lot less helpful... like he says, it's in some cases flat-out wrong. And then you go read the comments underneath in the hope of learning what you need to know... and you find a pile of junk even worse than the main docs, but with the occasional useful gem so you can't dismiss it out of hand. (But it's buried among loads of code whose primary purpose is to explain why there's so much bad PHP code out there.) Having lived through a year of PHP hell, I've developed a theory about the PHP ecosystem (i.e. docs, forums, user community, etc) vs. the Python ecosystem. When people ask PHP questions, the questions tend to be phrased as what do I type to get X, and the answers come back that way too. The forums are full of, I had the same problem. Somebody told me to do this. I don't really understand it, but it worked for me and maybe it'll work for you too. The Python ecosystem is much more about understanding what's actually happening. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
: On 26 February 2013 08:54, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation [...] [...] should we feel bad about Python's docs? The Python docs are my first port of call when I know the module (and maybe the function) I want to use, but can't remember exactly how it works. For that, and for me, they're very good. I can also usually find the section I want if I'm answering a beginner question on Stack Overflow and want to provide an explanatory link, but if I weren't already familiar with the docs, I think it's quite unlikely I'd find the relevant page easily. I agree with joepie91 that the information on fundamental stuff is poorly organised. I don't think that either the Python documentation or community is as bad as JoePie91 suggests. I think he has a point, albeit exaggerated, regarding the community - or at least python-list, which is the part with which I'm familiar. This list can be a little imposing for beginners, and its habit of veering away from the original question into an esoteric discussion of the language, while entertaining and educational to read for *me*, might well end up causing OP to scratch their head. I don't think it's intended, but sometimes there's also the sense that regulars here are trying, not entirely successfully, to hide their impatience with simple questions. I don't hang out at python-tutor, so maybe it's better there (in which case, maybe its existence needs to be better advertised). I think Stack Overflow is a little better at that, possibly because the rep system there encourages grinding in the MMORPG sense, and easy questions get a bunch of people piling on with answers almost instantaneously. -[]z. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Tue, Feb 26, 2013 at 7:54 AM, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. But should we feel bad about Python's docs? I don't think that either the Python documentation or community is as bad as JoePie91 suggests. Who's we? As a user of Python I feel no responsibility for the state of Python's documentation ;) Do I feel like it could be improved? Sure. I've never understood why Python doesn't document information about possible errors inside the function documentations. Instead, you have to read the exception documentation to find out when it might be raised, and then the exact error conditions aren't always clearly specified at all. My understanding from talking to members of the development team has been that this is by design, so I've of course never submitted a patch. (Well, I won't speak for the people on Freenode's #python. It took me approximately three minutes to be banned from there, with no warning or explanation.) I'm an op in #python. If you can provide logs or a nickname I could look into this with whoever banned you (if the ban hasn't expired already!) However, you should appreciate that, having only been there for three minutes, you may not have understood the expectations #python sets on tone or subject matter. It is markedly more strict than comp.lang.python. Also, bans aren't explained (except possibly in the kickban message, but that's rare) unless you ask about them. It's very easy to infer a reason from context, explanations take time (if you explain before the ban), and PMs to a just-banned person never go well (if you explain after the ban). As to whether or not JoePie91's observations are correct for #python... all the observations would apply to #python except for the ostrich and source-reading complaints, albeit viewed through a very negative light. I would disagree with his explanations for the reasons for things, and his ranking of the importance of things. IMHO the most important flaw in #python is that it's unwelcoming to new programmers, but I can't think of a decent way to fix that. Tutoring new programmers takes a huge amount of time. At the moment I figure that the best we can hope to do is identify them before we confuse the hell out of them by telling them to use classes, generators, higher order functions, and other intermediate to advanced topics. Unfortunately, we're not good at this. (Yet? :) By the way, interestingly enough, JoePie91 was in #python discussing his blog post for a bit. It was a fun conversation. -- Devin -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith r...@panix.com wrote: When people ask PHP questions, the questions tend to be phrased as what do I type to get X, and the answers come back that way too. The forums are full of, I had the same problem. Somebody told me to do this. I don't really understand it, but it worked for me and maybe it'll work for you too. A problem that's majorly exacerbated by the myriad ways of doing some things, with some of those ways deprecated and others theoretically plausible but hopelessly impractical. Here's an actual example that came up today at work. Suppose you have a user-provided string that's supposed to contain a URL, and you need to ensure that it doesn't have a trailing slash, so you can later add /foo or /bar. (Or alternatively, ensure that it DOES have a trailing slash. Either works.) Start the timer, go find out how to do it. Assume you are broadly familiar with PHP, and know how to do the basics of string handling, and are competent at searching the web. Ready? Go! I'll wait for you to come back. ... Okay, some of you are back now. Just giving the stragglers time to finish losing their marbles... Alright. Here's what I found in a recreation of today's search. Google search: php last character of string http://php.net/manual/en/function.substr.php -- okay, so I can use substr, but not string indexing, to find out what the last character is -- Returns the extracted part of string; or FALSE on failure, or an empty string. What kind of failures result in FALSE, and what kind in an empty string? http://stackoverflow.com/questions/4427172/find-last-character-in-a-string-in-php Comment on question: There are more than 10 ways of doing this! The accepted answer, fortunately, is a good one. Use rtrim. Okay. That's nice. But look at the other answers: one mentions substr (as above, that's half the question); one suggests the unwieldy form of indexing from the back (with an explicit strlen); one answers altogether the wrong question (suggesting the use of basename); and one... suggests a regular expression. Now you have two problems. And just to add to the pile of ways this could be done, the first response in this thread https://forums.digitalpoint.com/threads/how-to-get-last-character-in-string.796134/ suggests *reversing the string* and indexing from the front. Maybe you tried different search terms and got better results, I don't know. This wasn't the only search I did in trying to find the best way to do this, but it was the one with the most amusing results. The original rant specifically excluded sites like Stack Overflow as valid sources, which in a way is fair enough. But it wasn't from php.net that I got that information. Okay. Now I'll try it again, for Python. Google search: python last character of string First result: 3.1.2 Strings docs.python.org/release/1.5.1p1/tut/strings.html Besides numbers, Python can also manipulate strings, which can be expressed ... word[-1] # The last character 'A' word[-2] # The last-but-one character 'p' ... The use of code with directly connected comments means that I can read this part of the solution right there, without even clicking the link. Search Engine Optimization FTW. Searching for the second part, by adding the word 'remove' to the search, brings up more third-party sites - for PHP: http://www.if-not-true-then-false.com/2010/php-remove-last-character-from-string/ and for Python: https://groups.google.com/forum/?fromgroups#!topic/comp.lang.python/TIX5u3Zhikc http://stackoverflow.com/questions/9639754/python-remove-last-char-from-string-and-return-it In both cases, answering the question, but not from the language's own site. Forcing the matter with a site: search brings up poor results for both languages. Python gives me: http://docs.python.org/release/2.6/library/string.html but nothing about slicing. PHP: Take your pick of functions, and I hope you already know what they do, because the snippets don't help you choose: substr, rtrim, chop (which, once you go to the page, reveals itself to be an alias for rtrim), strrpos, substr_replace, strstr I'd have to say that, in the shoot-out, both languages died on their own merits, but stood on the merits of third-party support. Fifteen years ago, I would have called that a critical failure; in the 90s, I would search for information only from official sources. But these days, forum archives and blogs are some of the best way to find what you need - granted, Sturgeon's Law applies, but frankly that applies to a lot of documentation too (and Google's fairly good at helping you find the 10%). ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wed, 27 Feb 2013 01:26:47 +1100, Chris Angelico wrote: And just to add to the pile of ways this could be done, the first response in this thread https://forums.digitalpoint.com/threads/how-to-get-last-character-in- string.796134/ suggests *reversing the string* and indexing from the front. Oooh, deja vu! It's like it's 1988 and I'm learning to program in Hypertalk all over again! -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2013-02-26, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: The Python documentation is bad, and you should feel bad. Ahh! A point at which I can interject. As a rank green python noob, I definitely hava an opinion on python documentation and it's not entirely flattering. OTOH, it's hard to toss any other single linux based documentation up as a sterling example. IOW, I've seen worse. How am I learning about python? Several sources. The Non-Programmer's Tutorial docs from wikibooks was a false start. It goes for about 2 pages before I realized they've snuck in some python syntax without explaining it. So, I jump over to The Python Tutorial, which immediately leaves me submerged, as it's waaay over my clueless head. I flounder around and desperately grab onto Basic Python over at About.com. Finally, I'm rescued! Whoda thunk it? I usta despise About.com. But, they've matured greatly since their early days. I'm not a programmer. In fact I really dislike programming. But, as a long time linux user, I really need to learn a useful higher language. And here is this website that takes me by the hand and speaks to me like what I am. Dumb as a post and disinterested. But, they are patient. They explain basic programming concepts before launching into specifics. When they do get specific, they use simple examples that make sense. The don't toss in syntax they haven't fully explained. Great site and the one I'm now using to progress. I'm sure the other sites I've named will become helpful, eventually, but now I can move forward with confidence. Are python doc sites perfect? No. I've yet to come upon anything that clarifies why's and wherefores and the differences between the CMI IDLE and the GUI IDLE. And boy, are they different! OTOH, as I said, I've seen worse Linux docs. BitchX or zsh? What docs!? Even the man pages took me a long time to figure out. Bluefish? Krita? Puh-leeze! emacs? It's a wonder I can use it at all. ;) Despite all that, I'd say python documentation is better than a poke in the eye with a sharp stick. I'm sure the official pages will make more sense to me when I understand more. As it is, they jes toss out lc-letter like I know what they're talking about. They explain it a little bit, but I still hadda wiki it to get the full story. As a person with some technical writing experience, I know how difficult it can be. I had to be careful about who I was writing for, engineers or laymen. It's the same with programming docs. Writing tutorials about python as if I jes came from 5 yrs as a C programmer is not in the least bit helpful to a beginner like myself. Sometimes, one jes hasta hunt for the right flavor. nb -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
I think learning a language from the documentation is an unreasonable expectation and burden for the authors. Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals. I'm currently taking a class in ARM assembly, the notion that I should expect to plop the thousand+ page reference manual on my desk and just get to it is absurd. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2013.02.26 10:19, notbob wrote: zsh? What docs!? You mean other than the gigantic user manual? http://zsh.sourceforge.net/Doc/ -- CPython 3.3.0 | Windows NT 6.2.9200 / FreeBSD 9.1 -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2013-02-26 14:26, Chris Angelico wrote: On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith r...@panix.com wrote: When people ask PHP questions, the questions tend to be phrased as what do I type to get X, and the answers come back that way too. The forums are full of, I had the same problem. Somebody told me to do this. I don't really understand it, but it worked for me and maybe it'll work for you too. A problem that's majorly exacerbated by the myriad ways of doing some things, with some of those ways deprecated and others theoretically plausible but hopelessly impractical. Here's an actual example that came up today at work. Suppose you have a user-provided string that's supposed to contain a URL, and you need to ensure that it doesn't have a trailing slash, so you can later add /foo or /bar. (Or alternatively, ensure that it DOES have a trailing slash. Either works.) Start the timer, go find out how to do it. Assume you are broadly familiar with PHP, and know how to do the basics of string handling, and are competent at searching the web. Ready? Go! I'll wait for you to come back. ... Okay, some of you are back now. Just giving the stragglers time to finish losing their marbles... Alright. Here's what I found in a recreation of today's search. Google search: php last character of string http://php.net/manual/en/function.substr.php -- okay, so I can use substr, but not string indexing, to find out what the last character is -- Returns the extracted part of string; or FALSE on failure, or an empty string. What kind of failures result in FALSE, and what kind in an empty string? [snip] The page http://php.net/manual/en/function.substr.php says: Description string substr ( string $string , int $start [, int $length ] ) OK. It then goes on to say: Parameters string The input string. Must be one character or longer. What? The input string can't be an empty string? -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2013-02-26, Andrew Berg bahamutzero8...@gmail.com wrote: On 2013.02.26 10:19, notbob wrote: zsh? What docs!? You mean other than the gigantic user manual? http://zsh.sourceforge.net/Doc/ This document was generated by Simon Ruderich on July 24, 2012 'bout damn time!! ;) nb -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2013-02-26 17:54, notbob wrote: zsh? What docs!? You mean other than the gigantic user manual? http://zsh.sourceforge.net/Doc/ This document was generated by Simon Ruderich on July 24, 2012 'bout damn time!! ;) Generated...from source that has been around for ages: http://zsh.git.sourceforge.net/git/gitweb.cgi?p=zsh/zsh;a=history;f=Doc;hb=dd3b0506f99e690f521d9bf449dea47a51502cb2;pg=11 which suggests that they've been actively maintained since 1999-2000 or so. -tkc -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2/26/2013 7:54 AM, Steven D'Aprano wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ To me, this is a lying troll rant worth less than most of RantingRick's posts. It is valuable to contrast and compare the PHP and Python docs: http://php.net/manual/en/index.php http://www.python.org/doc/ The contrast has been discussed before on python-list and even pydev. To repeat: in my opinion, and that of most core developers, the python docs are superior. It is Joe's lie to equate difference of opinion with indifference. Python has a nice Tutorial for beginners. It is an integral part of the doc set. To ignore that (and the indexes) in discussing the usability of Python docs by beginners is to lie. (If beginners who actually read the tutorial have problems with particular paragraphs, improvements can be and have been made.) Examples: Once startup is explained, the rest of the tutorial is about half text and half example. I think that is a good balance. Anyone who reads the tutorial knows how to call a function. I think doubling the size of the Library *Reference* with trivial, repetitive examples like: len([1,2,3]) 3 would be a negative for reference use*. Python has a super-duper interactive mode for trying things like this oneself, and that teaches *better* than just reading the same thing. (And if the tutorial never discusses len() and its generic use for all concrete collections, it should.) * Anyone who disagrees can go to http://www.lightbird.net/py-by-example/builtin-functions.html where you can find that and other examples for builtins and about 30 modules. Actually, I can imagine that some beginners would benefit from this page as an extension of the tutorial. This site may be an outcome of the previous discussion, which more or less ended with the fact that anyone who wanted to produce php-style Python docs was free to do so. Searching: it is true that the Python docs are written for being read by people, rather than by search engines#. It has a hand-crafted index (yes, it still needs patches) that will get you most places, especially for anyone who has read the tutorial to get the basics. For 'length of a list' one can find 'len() (built-in function)' and find that 'len' indeed mean length and, more generally, size. # Anyone who wants to could develop an seo-optimized python-by-function website that goes into exquisite details for each function on a separate page. len(collection) = count Built-in function len() allows one to find the * length or size of a list * length or size of a tuple * length or size of an array * length or size of a string * length or size of a bytes * length or size of a bytearray * length or size of a memoryview * size of a set * size of a frozenset * size of a dict or dictionary * size of dict view * size of user-defined collecton class instances Returns 0 for empty collections. Raises TypeError for inputs that are not collections or that do not support len() calls, because they do not have a properly written .__len__ methods. If I were involved, I would *not* junk-up such pages with random user posts. Anything worth being added should be incorporated into the entry itself. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2013-02-26, Tim Chase python.l...@tim.thechases.com wrote: which suggests that they've been actively maintained since 1999-2000 or so. in various guises, dating back to the man pages. Not all as thorough as the latest manual. Perhaps I shoulda qualified usable docs. ;) nb -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Tue, Feb 26, 2013 at 11:38 AM, Adam W. awasile...@gmail.com wrote: I think learning a language from the documentation is an unreasonable expectation and burden for the authors. That's how I learned it. The Python tutorial, together with the stdlib reference manual, are often recommended to beginners to Python in order to learn it. The combination of the documentation and consulting other programmers helped me learn the language just fine. Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals. I would assert it isn't very kind to those even with basic fundamentals. For example, under precisely what circumstances does int() raise TypeError? You won't find that under either int's documentation, or TypeError's documentation, you have to look it up under __int__, which is _not_ a basic fundamental. And rather than helping you along the way, the documentation for int() actively misleads you by its implicature that the only acceptable types are strings, ints, and floats. And then even if you have the foresight to remember oh yeah, isn't there a special method for this?, you have to find the documentation for __int__, which is itself is three quarters of the way down this massive page: http://docs.python.org/2/reference/datamodel.html . -- Devin -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 02/26/2013 07:54 AM, Steven D'Aprano wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ It is valuable to contrast and compare the PHP and Python docs: http://php.net/manual/en/index.php http://www.python.org/doc/ There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. But should we feel bad about Python's docs? I don't think that either the Python documentation or community is as bad as JoePie91 suggests. (Well, I won't speak for the people on Freenode's #python. It took me approximately three minutes to be banned from there, with no warning or explanation.) Another response to the blog post, by one of the core developers: http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html I think the issue with python documentation is that it ignores the 95/5 rule: 95% of people who land on a module's page are only looking for 5% of its information. So ideally it'd be separated in two different pages or two sections of the same page, something like: === Hi, chances are you are the 95% of people who isn't interested in the intricacies, obscure edge cases et cetera. Here are the few common use cases for this module: ... ... ... === Hi, the section above obviously did not suit your needs, so you must be in the 5% who has no choice but to either read through or at least glance through, or use search, to find what you need in the following umpteen million of screenfuls: ... * 100 === Why doesn't Python do that? Quite simply, it's a lot more work: you have to separate most useful parts from the rest, which involves judgement calls and will cause some disagreement and ultimately won't be perfect. Once done, two separate sections need to be mainained and kept in sync. It's important that they don't contradict each other. Right now places like SO and mailing list act like the first section I described. The issue is that they're not always up to date and not guaranteed to be correct, are not in a consistent style and depth, are not centralized. -m -- Lark's Tongue Guide to Python: http://lightbird.net/larks/ Is life not a thousand times too short for us to bore ourselves? Friedrich Nietzsche -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Feb 26, 11:19 am, notbob not...@nothome.com wrote: On 2013-02-26, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: The Python documentation is bad, and you should feel bad. Ahh! A point at which I can interject. As a rank green python noob, I definitely hava an opinion on python documentation and it's not entirely flattering. OTOH, it's hard to toss any other single linux based documentation up as a sterling example. IOW, I've seen worse. How am I learning about python? Several sources. The Non-Programmer's Tutorial docs from wikibooks was a false start. It goes for about 2 pages before I realized they've snuck in some python syntax without explaining it. So, I jump over to The Python Tutorial, which immediately leaves me submerged, as it's waaay over my clueless head. I flounder around and desperately grab onto Basic Python over at About.com. Finally, I'm rescued! Whoda thunk it? I usta despise About.com. But, they've matured greatly since their early days. I'm not a programmer. In fact I really dislike programming. But, as a long time linux user, I really need to learn a useful higher language. And here is this website that takes me by the hand and speaks to me like what I am. Dumb as a post and disinterested. But, they are patient. They explain basic programming concepts before launching into specifics. When they do get specific, they use simple examples that make sense. The don't toss in syntax they haven't fully explained. Great site and the one I'm now using to progress. I'm sure the other sites I've named will become helpful, eventually, but now I can move forward with confidence. Are python doc sites perfect? No. I've yet to come upon anything that clarifies why's and wherefores and the differences between the CMI IDLE and the GUI IDLE. And boy, are they different! OTOH, as I said, I've seen worse Linux docs. BitchX or zsh? What docs!? Even the man pages took me a long time to figure out. Bluefish? Krita? Puh-leeze! emacs? It's a wonder I can use it at all. ;) Despite all that, I'd say python documentation is better than a poke in the eye with a sharp stick. I'm sure the official pages will make more sense to me when I understand more. As it is, they jes toss out lc-letter like I know what they're talking about. They explain it a little bit, but I still hadda wiki it to get the full story. As a person with some technical writing experience, I know how difficult it can be. I had to be careful about who I was writing for, engineers or laymen. It's the same with programming docs. Writing tutorials about python as if I jes came from 5 yrs as a C programmer is not in the least bit helpful to a beginner like myself. Sometimes, one jes hasta hunt for the right flavor. nb For me on the other hand. The Python tutorial has been the most useful tutorial I have ever used. I had experience with Basic and Pascal. Most other tutorials go too slow for me and I loose interest. The python one just kept going and after reading the dozen pages in a couple of hours I had enough of an idea about the language to start doing the things I was interested in. The only thing that confused me at first was finding functions like open or input and string methods. I lost a bit of time searching in the language reference until I found out that they are in the Library reference: I didn't think of open as a library. But now I have no problem; all I need is found under Library reference in section 2 and 4 and starting with section 6. I also use the global module index when I already have an idea what I am looking for. What it could have is better searching capability and a way to see more examples. Examples would clutter the documentation so maybe they should be collapsible, but you can never have enough examples. As Einstein said: “Example isn't another way to teach, it is the only way to teach” Outside of the tutorial there are not a lot of succinct examples of more advanced uses of the different keywords and builtins. Thankfully for the libraries there is Python Module of the Week for people that know about it. -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 26/02/2013 12:54, Steven D'Aprano wrote: One week ago, JoePie91 wrote a blog post challenging the Python community and the state of Python documentation, titled: The Python documentation is bad, and you should feel bad. http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- and-you-should-feel-bad/ It is valuable to contrast and compare the PHP and Python docs: http://php.net/manual/en/index.php http://www.python.org/doc/ There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. But should we feel bad about Python's docs? I strongly disagree with most of what the author writes. To start with, there's this: Let’s start out with a simple example. Say you are a developer that just started using PHP, and you want to know how to get the current length of an array. You fire up a browser and Google for “PHP array length site:php.net”. The first result is spot-on, and one minute later, you know that count($arr) will suffice. Now let’s say that you wish to do the same in Python. In this case, you would Google for “Python list length site:docs.python.org”, and the first result is… a page with several chapters on standard types? It seems to me that this is /completely/ the wrong way for a developer who's new to Python to go about learning the language. If you don't know enough Python to be familiar with len(), the sensible thing to is not to try coding by finding out individual language features as and when you need them, but to read the tutorial, systematically from start to finish. This list is continually being bombarded with questions from people who tried the former only to become stuck when something didn't work the way they thought it should (I've been guilty of this too), because knowing vocabulary is not the same thing as knowing how a language works. The majority of such questions could have been answered by simply reading the tutorial. More still could be answered by reading the language reference, which really isn't very long. That's not to say that experienced users don't need to look things up, but then why would one restrict a web search to docs.python.org? Almost every question I've had about how to do something in Python has already been asked at StackExchange, and Google will find it. When you Google for something, you will end up on a page that explains a lot of things, including what you’re looking for. But how are you supposed to know where on the page it is, or whether it’s even on the page at all? The problem here is that the particular operation you are trying to find documentation on, does not have its own page. And the solution is Ctrl-f. The general norm for the Python community appears to be that if you are not already familiar with the language, you do not deserve help. If you do something in a less-than-optimal way, other Python developers will shout about how horrible you are without bothering to explain much about what you did wrong. When you ask out of curiosity how a certain thing works, and that thing is considered a bad practice, you will get flamed like there’s no tomorrow – even if you had no intention of ever implementing it. This is not my experience at all. Even when asking questions that I could have answered myself if I had RTFM, I've received helpful advice and nothing that could be construed as a flame. I don't know how this compares to other programming language communities, but it's much friendlier to newcomers here than, say, sci.math (whose competent regulars are understandably suspicious of people asking idiotic questions, given how many of those people turn out to be cranks). PHP solves [ambiguity] by having examples for every single function and class. If you’re not sure what is meant with a certain sentence in the description, you just look at one of the included examples, and all ambiguity is removed. It’s immediately obvious how to use things. Python solves this by having an interactive interpreter. The tutorial goes to the trouble of pointing out that [i]t helps to have a Python interpreter handy for hands-on experience. If you are an experienced developer, then you are most likely in a very bad position to judge how beginner-friendly the documentation for a language is. [...] Most of all, accept that your personal experiences with Python, as an experienced developer, are not worth very much. Listen to the newbies when they tell you the documentation is hard to read or find stuff in. But I'm not an experienced developer. I'm an amateur hobbyist who came to learn Python having only had any real programming experience with BBC BASIC and OPL (both as a child). I read the tutorial, then I read the language reference, now I'm reading the library reference. They're all fine. -- I have made a thing that superficially resembles music:
Re: Do you feel bad because of the Python docs?
Just to throw in my 2c -- in the same way that 'a picture is worth a thousand words', an interactive interpreter is worth volumes of documentation (especially one with such a nice help()/__doc__ functionality). It's worth pointing out that 'interpreter' appears in the original rant once (according to ctrl-F, whole thing was tl;dr): Want to know how the Python interpreter deals with input Y? Read the source. And so on, and so on. Not: Open up an interpreter and input Y You aren't sure what errors are thrown by a particular function? Fire up an interpreter and feed the function junk. You'll get your answer faster than you can Google, and often learn neat stuff along the way. (I recall one of RR's posts that actually had some good tips to learn-via-interpreter). Also, I'll bet the way I learned Python effectively would seem like nails-on-a-chalkboard to others -- and vice versa. The 'one-size-fits-all' doesn't work for documentation. Complete and concise often battle, with no clear winner. And his representation of the Python community does not appear to be representative of my experience (threads begun via trolling rants notwithstanding). But he's ranting on his blog; not a big deal really. --Jason -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 02/26/2013 11:00 AM, nn wrote: What it could have is better searching capability and a way to see more examples. Examples would clutter the documentation so maybe they should be collapsible, but you can never have enough examples. A good resource (although only covering up to v2.3) is effbot's guide to the standard library available at http://effbot.org/zone/librarybook-index.htm It's pretty much _all_ examples. Emile -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. But should we feel bad about Python's docs? I don't think so at all. I think the python docs are quite well organized. Who googles for python knowledge when you can just go to the official site and use the doc search? Mark -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Tuesday, February 26, 2013 4:17:22 PM UTC-6, Jason Swails wrote: Just to throw in my 2c -- in the same way that 'a picture is worth a thousand words', an interactive interpreter is worth volumes of documentation (especially one with such a nice help()/__doc__ functionality). Yes! I don't even know why people care about the Python docs anyway. One of the most under-appreciated (and maybe even unknown) aspects of the Python language is the power of doc strings and the help function. Not to mention the awesome introspection capabilities via a few built-in functions: id(obj) isinstance(obj, type) issubclass(obj, klass) repr(obj) type(obj) bool(obj) dir(obj) ... As for the docs: I would say that if you are searching for a particular something (and the help function has failed you), then skip the docs and use Google instead. The docs only seem to work well when read in a linear fashion; with exception of the global module index and the language reference sections. As for the official tutorial, do yourself a favor and DON'T read it (or never read it) until AFTER you are comfortable with python. It's not so much that the tutorial is lacking, it's more that the tutorial uses poor example code and as such is an abomination. That's my opinion anyway. There are tons of great python tutorials on the web. You aren't sure what errors are thrown by a particular function? Fire up an interpreter and feed the function junk. You'll get your answer faster than you can Google, and often learn neat stuff along the way. Yes! Interactive sessions are what make python so damn great! If you don't have an editor window and a shell window open when writing (python) code, you are doing something wrong. (I recall one of RR's posts that actually had some good tips to learn-via- interpreter). I don't remember the exact thread off-hand, but i must admit you can find loads of great information in my threads! :-P -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Wed, Feb 27, 2013 at 12:15 PM, Mark Janssen dreamingforw...@gmail.com wrote: On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: There's no doubt that one of PHP's strengths, perhaps its biggest strength, is the good state of documentation. But should we feel bad about Python's docs? I don't think so at all. I think the python docs are quite well organized. Who googles for python knowledge when you can just go to the official site and use the doc search? I'm not sure if you're trolling or not... The python.org search is one of its weakest attributes; on the main http://python.org/ search, it's now been replaced by a Google site-search, but the box on the side in http://docs.python.org/ still gives the annoyingly slow internal search. So no, I don't go to the official site search, I use Google (with or without site:python.org to restrict the results - most often without). ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
Hi I'm a Python enthusiast who originally found the Python docs at python.org to be one of the main reasons that my enthusiasm was fed. Also the thoughtful presence of docstrings throughout good projects and libraries gives me the feeling that finding out how to do something in Python is just as easy as finding out how to do something else in PHP. -- Regards, Jerome Music http://www.jeromecovington.com/music/ || Web Devhttp://www.jeromecovington.com/dev/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2/26/2013 1:52 PM, Devin Jeanpierre wrote: I would assert it isn't very kind to those even with basic fundamentals. For example, under precisely what circumstances does int() raise TypeError? You won't find that under either int's documentation, or TypeError's documentation, you have to look it up under __int__, which is _not_ a basic fundamental. And rather than helping you along the way, the documentation for int() actively misleads you by its implicature that the only acceptable types are strings, ints, and floats. And then even if you have the foresight to remember oh yeah, isn't there a special method for this?, you have to find the documentation for __int__, which is itself is three quarters of the way down this massive page: http://docs.python.org/2/reference/datamodel.html Have you opened an issue, or checked for existing issue? I would be open to the idea that entries like that for int should not be overly type specific and imply that the defaults are the only possibilities. Perhaps there should be a cross-reference to corresponding special methods. Perhaps that idea might be opposed. I am not sure. Perhaps Built-in Functions needs a bit more general explanatory text at the top. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 2/26/2013 1:58 PM, Mitya Sirenef wrote: I think the issue with python documentation is that it ignores the 95/5 rule: 95% of people who land on a module's page are only looking for 5% of its information. So ideally it'd be separated in two different pages or two sections of the same page, something like: === Hi, chances are you are the 95% of people who isn't interested in the intricacies, obscure edge cases et cetera. Here are the few common use cases for this module: ... ... ... === Hi, the section above obviously did not suit your needs, so you must be in the 5% who has no choice but to either read through or at least glance through, or use search, to find what you need in the following umpteen million of screenfuls: ... * 100 === Why doesn't Python do that? We are not literally going to write text like that, but we did recently re-organized the doc for one module specifically to put the most commonly used stuff (about the 'convenience' functions) at the top instead of buried where it was. Quite simply, it's a lot more work: you have to separate most useful parts from the rest, which involves judgement calls and will cause some disagreement and ultimately won't be perfect. Once done, two separate sections need to be mainained and kept in sync. In the case above, there is no duplication to be kept in sync. More the problem is that people working of the docs tend to either leave or move on to code. Report like 'This section is unclear' are not too helpful either. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On Tue, 26 Feb 2013 17:48:27 +, MRAB wrote: On 2013-02-26 14:26, Chris Angelico wrote: On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith r...@panix.com wrote: When people ask PHP questions, the questions tend to be phrased as what do I type to get X, and the answers come back that way too. The forums are full of, I had the same problem. Somebody told me to do this. I don't really understand it, but it worked for me and maybe it'll work for you too. A problem that's majorly exacerbated by the myriad ways of doing some things, with some of those ways deprecated and others theoretically plausible but hopelessly impractical. Here's an actual example that came up today at work. Suppose you have a user-provided string that's supposed to contain a URL, and you need to ensure that it doesn't have a trailing slash, so you can later add /foo or /bar. (Or alternatively, ensure that it DOES have a trailing slash. Either works.) Start the timer, go find out how to do it. Assume you are broadly familiar with PHP, and know how to do the basics of string handling, and are competent at searching the web. Ready? Go! I'll wait for you to come back. ... Okay, some of you are back now. Just giving the stragglers time to finish losing their marbles... Alright. Here's what I found in a recreation of today's search. Google search: php last character of string http://php.net/manual/en/function.substr.php -- okay, so I can use substr, but not string indexing, to find out what the last character is -- Returns the extracted part of string; or FALSE on failure, or an empty string. What kind of failures result in FALSE, and what kind in an empty string? [snip] The page http://php.net/manual/en/function.substr.php says: Description string substr ( string $string , int $start [, int $length ] ) OK. It then goes on to say: Parameters string The input string. Must be one character or longer. What? The input string can't be an empty string? Huh, this is PHP. You're lucky it doesn't say: The input string. Must be one character or longer, except for the case- insensitive string 'something-magical-happens-here'. *wink* -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
Subject: Re: Do you feel bad because of the Python docs? To: python-list@python.org Cc:Bcc: -=-=-=-=-=-=-=-=-=# Don't remove this line #=-=-=-=-=-=-=-=-=- On 02/26/2013 09:00 PM, Terry Reedy wrote: On 2/26/2013 1:58 PM, Mitya Sirenef wrote: I think the issue with python documentation is that it ignores the 95/5 rule: 95% of people who land on a module's page are only looking for 5% of its information. So ideally it'd be separated in two different pages or two sections of the same page, something like: === Hi, chances are you are the 95% of people who isn't interested in the intricacies, obscure edge cases et cetera. Here are the few common use cases for this module: ... ... ... === Hi, the section above obviously did not suit your needs, so you must be in the 5% who has no choice but to either read through or at least glance through, or use search, to find what you need in the following umpteen million of screenfuls: ... * 100 === Why doesn't Python do that? We are not literally going to write text like that, but we did recently re-organized the doc for one module specifically to put the most commonly used stuff (about the 'convenience' functions) at the top instead of buried where it was. Yes, I didn't mean it would be literally worded like that :-). Quite simply, it's a lot more work: you have to separate most useful parts from the rest, which involves judgement calls and will cause some disagreement and ultimately won't be perfect. Once done, two separate sections need to be mainained and kept in sync. In the case above, there is no duplication to be kept in sync. More the problem is that people working of the docs tend to either leave or move on to code. Report like 'This section is unclear' are not too helpful either. I don't think that would work in the general case, for all modules, because the 'inclusive' section should not be missing items that logically belong there. For example, if I'm looking through string formatting subsection, it would be confusing if some items were missing because they were moved to the top together with other items from different subsections. In addition, the 'inclusive' section would have some advanced notes that would not be included in the first section, even if items themselves may be there. For example, let's take timedelta section: http://docs.python.org/2/library/datetime.html#timedelta-objects At the end of this section there is a dozen lines of helpful examples. I think vast majority of visitors need these examples (not a complete list, just an example of examples), and it would be ideal if they were shown at the very top of the page, without the need to scroll down: from datetime import timedelta, datetime three_days = timedelta(days=3) datetime.now() datetime.datetime(2013, 2, 26, 21, 45, 44, 371334) datetime.now() + three_days datetime.datetime(2013, 3, 1, 21, 45, 34, 427403) old_date = datetime(2013, 2, 10) if datetime.now() - old_date timedelta(days=10): ... print(It's been more than 10 days since %s % old_date) It's been more than 10 days since 2013-02-10 00:00:00 year = timedelta(weeks=40, days=84, hours=23, ... minutes=50, seconds=600) # adds up to 365 days year.total_seconds() 31536000.0 (As a side note, I think it would be better if sections in datetime were in separate pages, it would be easier to google and the navbar on the left side is very crowded and rather hard to read - often I find myself missing stuff that's in there and ending up just scrolling down through the document until I find what I need -- it might be better if section numbers were not included there, font for keywords was not fixed width font, and topics didn't wrap so much - in case of datetime, all of the topics have enough horizontal space not to wrap and yet 3 out of 7 do wrap!) Of course, it can be argued that these are minor issues, that relevant parts of documentation are still quite easy to get to, and if it takes a few minutes longer, it's not the end of the world. In my view, such small matters are more important than it looks, because working on a project requires focus and if you spend just a few minutes hunting around the doc pages, you start to lose the larger picture of your design... I tend to remember the most important modules out of standard lib because I've worked with them a lot in the last few years, but I imagine it can be tough for people who program a bit as a hobby or as a small part of their job. I don't mean to say that Python docs are terrible, though. They're quite good, especially as more examples were added in the last few years
Re: Do you feel bad because of the Python docs?
On Tuesday, February 26, 2013 7:48:51 PM UTC-6, Terry Reedy wrote: On 2/26/2013 1:52 PM, Devin Jeanpierre wrote: [...snip legit complaint...] Have you opened an issue, or checked for existing issue? I would be open to the idea that entries like that for int should not be overly type specific and imply that the defaults are the only possibilities. Terry (with all due respect), do you /really/ expect that people have the time to open an issue on the bug tracker? Do you really think that everyone who uses python even knows about the bug tracker? Do you really think that people will believe that their opinion is worthy of placing on the bug tracker? Do you really? I think most will just end up ignoring the docs and either be forced to give up on Python or look for documentation elsewhere. Now, you could react to that truth by saying: Well, who cares! The docs are the docs and if people can't grok them then too bad for them because i think they are awesome. Sadly (in actuality) it's too bad for *you* Terry (along with the many other people who maintain docs) when you ignore the many request for changes. Remember, if people just ignore the docs because of these abominations you and everyone else are basically wasting your time maintaining the docs! Do you understand this fact? Terry Implies: We will write the docs how *we* see fit, and to hell with your feeble misunderstandings. You are beneath us! *We* are the anointed ones. *We* know everything! Look i know your intentions are noble, and yes my wording was a bit theatrically unfair, but this is /exactly/ how people are interpreting your intentions Terry. Please don't become a zealot. Python will never be perfect! I can assure you. And besides, is a bug tracker /really/ the place to voice the many legitimate problems concerning python's documentation or stdlib? Forgive me, but I thought bug trackers where for tracking ,umm... well, BUGS! This is why i mentioned the need for an official PyWarts (group or list) so these folks will have a platform to voice their frustrations. A very PUBLIC and very ACCESSIBLE and very WELL KNOWN platform. Because if IS NOT all three of these things, then it IS nothing. But you cannot just hand them a microphone and then stick your fingers in your ears. You need to /listen/ carefully and try to place yourself into their shoes. I can assure you that the Python docs, and the language itself, could use some polishing. Stop taking these complaints personally and start listening with an objective ear; please? -- http://mail.python.org/mailman/listinfo/python-list
Re: Do you feel bad because of the Python docs?
On 02/26/2013 10:09 PM, Mitya Sirenef wrote: (As a side note, I think it would be better if sections in datetime were in separate pages, it would be easier to google and the navbar on the left side is very crowded and rather hard to read - often I find myself missing stuff that's in there and ending up just scrolling down through the document until I find what I need -- it might be better if section numbers were not included there, font for keywords was not fixed width font, and topics didn't wrap so much - in case of datetime, all of the topics have enough horizontal space not to wrap and yet 3 out of 7 do wrap!) In regard to Python doc topic menu readability -- compare to the django topic menu: https://docs.djangoproject.com/en/dev/topics/db/queries/ It's ridiculous how much more readable it is, at least to my eyes! -m -- Lark's Tongue Guide to Python: http://lightbird.net/larks/ -- http://mail.python.org/mailman/listinfo/python-list
