Re: Python documentation too difficult for beginners
In message mailman.580.1288818221.2218.python-l...@python.org, Cameron Simpson wrote: But its weakness is stuff like this: http://epydoc.sourceforge.net/stdlib/Canvas.Polygon-class.html Automatic docness, no useful information. But it Conforms to Documentation-Production Metrics as decreed by the Corporate Task Force on Policy. So long as the divisions are satisfying the official metrics on documentation production, that must mean the project is meeting its goals. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 11/02/2010 02:42 PM, Steven D'Aprano wrote: However, there is a Python wiki. It doesn't get anywhere near as much love as it deserves, and (I think) the consensus was that the official Python docs should stay official, but link to the wiki for user- contributed content. This hasn't happened yet. http://wiki.python.org/moin/ That sounds like an excellent idea. I often would have appreciated more examples or discussions about a given module/class/function without having to fall back to Google. It might be a good compromise: clearly separating official doc and examples, but accepting, that the doc is often insufficient without digging into the sources or searching for more xamples. The more one uses python, the easier it becomes to find what one looks for. My first Impression about Python however was: - the basic language is rather easy to learn - the library documentation was more difficult to understand than the one for PHP or for Perl. Frankly, I think that the best thing you could do is start a fork of the docs and see if you get any interest from people. If you do, then you can go back to python-dev with proof that there is a genuine popular desire for more structured, PHP-style documentation. I'd prefer crosslinking the doc with something, that's easier for beginners of for people who never used a given library before. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
In message mailman.542.1288760105.2218.python-l...@python.org, Dennis Lee Bieber wrote: Whereas I have a whole shelf of Java documentation and it still takes me an hour to write Hello World... Java's one class per file results in a plethora of bloody names one has to remember just to find out where to start looking for a standard library operation. You know Alan Kay’s dictum that “simple things should be simple, and complex things should be possible”? Well, Java isn’t designed to make simple things simple. :) -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Nov 2, 11:06 pm, Lawrence D'Oliveiro l...@geek- central.gen.new_zealand wrote: In message a5dc65e1-3a72-4160-90e3-956a456be...@26g2000yqv.googlegroups.com, jk wrote: This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking about. Framesets? Is that really your idea of well-laid-out documentation? Using a feature which has been derided (and dropped in HTML5) because of its effect on usability and accessibility? No, the framesets suck, and I agree that Javadoc isn't perfect. Actually, I do think the PHP docs are the best I've found as a reference. Javadocs just need a few tweaks and they'd be better (an index at the top so you don't have to scroll down, no framesets, a search engine). Still think they're better than the python docs though. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
Steven D'Aprano writes: On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote: The former is difficult to find (try searching for 'open' in the search box and see what you get). A fair point -- the built-in open comes up as hit #30, whereas searching for open in the PHP page brings up fopen as hit #1. But the PHP search also brings up many, many hits -- ten pages worth. But in any case, the Python search functionality could be smarter. If I had a complaint about the docs, that would be it. Fortunately, I have google :) Actually that was one of the hair-tearing attitudes I heard a web search guru complain about. The smartest part of the search engine is the people running it, so why not apply their brains directly? Read the log like you did, look for poor results (like open), put in exceptions by hand. This might be a fraction of the work it takes to program that kind of smarts into the engine. Or you might discover a group of exceptions to put in - like all Python keywords. That makes it at least partially programmed, which may be preferable. -- Hallvard -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 02Nov2010 03:42, jk sanjo...@yahoo.com wrote: | I've been coding in PHP and Java for years, and their documentation is | concise, well structured and easy to scan. While I agree about Java, at least the core Java docs, and javadoc output in general (_great_ cross referencing!) I have mixed feelings about the PHP docs. Though I suspect that stems from a dislike of the PHP library API in general more than the docs, perhaps. | Others have mentioned this apparently for years (see: | http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851 | and http://www.russellbeattie.com/blog/python-library-docs-still-suck | and http://xahlee.org/perl-python/xlali_skami_cukta.html). | | Compare for instance the differences in ease of use, and speed of use, | of these: | | http://docs.python.org/library/functions.html#open | http://uk.php.net/manual/en/function.fopen.php | | The former is difficult to find (try searching for 'open' in the | search box and see what you get). I confess I almost never use the search box - as you say the result relevance can be dodgy. However, I do find the docs easy to use and pleasant to read on the whole. My use is as follows: For speed and convenience I have the docs locally stored. I open the front page and then usually both the modules and index in adjacent brwoser tabs. I go to the index if I'm not sure of the module. The strength of the index is that it tends to contain stuff that people thought should be indexed (versus searches, which often have no contextual understanding of the text, so their relevance is weaker). The weakness of the index is that it can be hard to pick the relevant entry. Open-link-in-new-tab is my friend here:-( | It is simply a collection of | paragraphs without strong enough contrast to differentiate the | different parts - parameters, parameter values, return types, | exceptions and related functions. It is slow to read and doesn't allow | easy visual scanning. That is true (the scanning). But by contrast, it does read like prose and lends itself to a visit that gets you a complete feel for the function. [...] | Has anyone else struggled while trying to learn the language? The | whole documentation system seems geared towards people who already | know what they're looking for and is close to useless for beginners. | I'm not the only one who finds google an easier way to find | documentation about python. I certainly don't find the core docs hard to use (with some exceptions; I still don't really understand the urllib stuff for the cases where configuration is needed - weird proxy setups etc). I've only been using Python for a few years and have generally found that language easy to learn and the docs easy to read. I rarely reach for The Google unless I'm seeking examples; the docs could do with a few more of these IMHO. I understand the attraction of the structured layout javadoc yields but find it leads to drier documentation. It also works well for Java because it is strongly typed - a great deal of the structure in the docs can come directly from the code because argument counts, names and types are always explicit (or deducable). These are just initial responses. Now to wade the whole thread:-) -- Cameron Simpson c...@zip.com.au DoD#743 http://www.cskk.ezoshosting.com/cs/ On the contrary of what you may think, your hacker is fully aware of your company's dress code. He is fully aware of the fact that it doesn't help him to do his job. - Gregory Hosler gregory.hos...@eno.ericsson.se -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 02Nov2010 04:23, jk sanjo...@yahoo.com wrote: | This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking | about. | | Why aren't the official docs like this, and why has it taken me 2 days | of searching? All this needs is a search engine behind it and it'd be | perfect. It looks a lot like javadoc. But its weakness is stuff like this: http://epydoc.sourceforge.net/stdlib/Canvas.Polygon-class.html Automatic docness, no useful information. And of course the ugliness; I find the python docs much nicer to look at. But I do wish the cross referencing was a bit better, often. -- Cameron Simpson c...@zip.com.au DoD#743 http://www.cskk.ezoshosting.com/cs/ In an insane society, the sane man must appear insane. - Keith A. Schauer ke...@balrog.dseg.ti.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Thu, 04 Nov 2010 08:03:37 +1100, Cameron Simpson wrote: On 02Nov2010 04:23, jk sanjo...@yahoo.com wrote: | This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking | about. | | Why aren't the official docs like this, and why has it taken me 2 days | of searching? All this needs is a search engine behind it and it'd be | perfect. It looks a lot like javadoc. But its weakness is stuff like this: http://epydoc.sourceforge.net/stdlib/Canvas.Polygon-class.html Automatic docness, no useful information. You get the same problem in Java and it has exactly the same root: a lazy programmer who can't be arsed to document his code. -- martin@ | Martin Gregorie gregorie. | Essex, UK org | -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
If you are really beginner in python you can look into the dive into python,search as in google as the same its quite helpful for beginners.Also you can go for the byte of python. CHEERS CNA 9986229891 On Tue, Nov 2, 2010 at 4:42 PM, jk sanjo...@yahoo.com wrote: Hi, I've been coding in PHP and Java for years, and their documentation is concise, well structured and easy to scan. Others have mentioned this apparently for years (see: http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851 and http://www.russellbeattie.com/blog/python-library-docs-still-suck and http://xahlee.org/perl-python/xlali_skami_cukta.html). Compare for instance the differences in ease of use, and speed of use, of these: http://docs.python.org/library/functions.html#open http://uk.php.net/manual/en/function.fopen.php The former is difficult to find (try searching for 'open' in the search box and see what you get). It is simply a collection of paragraphs without strong enough contrast to differentiate the different parts - parameters, parameter values, return types, exceptions and related functions. It is slow to read and doesn't allow easy visual scanning. The latter has clearly delineated, standardised content areas for each of these without excessive text. It uses tables which are easy to scan for possible opening modes and allows users to contribute their own examples. Sadly, the use of restructured text by python doesn't allow a new document generator to be written - all existing documentation would need updating with docblocks or something similar. Has anyone else struggled while trying to learn the language? The whole documentation system seems geared towards people who already know what they're looking for and is close to useless for beginners. I'm not the only one who finds google an easier way to find documentation about python. Is there much chance that the Python maintainers will change their documentation system to make it more like Java or PHP? How would I go about trying to make that happen? -- http://mail.python.org/mailman/listinfo/python-list -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking about. Why aren't the official docs like this, and why has it taken me 2 days of searching? All this needs is a search engine behind it and it'd be perfect. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 02/11/2010 11:23, jk wrote: This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking about. Why aren't the official docs like this, and why has it taken me 2 days of searching? All this needs is a search engine behind it and it'd be perfect. I'm glad you find the epydoc format useful. And I'm glad that various people have taken the trouble to produce documentation for Python in various formats that suit them. But why do you imagine that the core Python documentation -- developed and maintained by a group of people who clearly have some idea what they're doing -- should change to a format which happens to suit you? The Python documentation source and the source code of Python itself are all freely available. Any initiative by you or by others to produce alternative, possibly searchable and commentable, versions of them would I'm sure be welcomed by many. But not everyone finds, eg, the PHP style of user annotation helpful. Not everyone likes epydoc output: I don't myself. In short, please feel free to contribute directly to the core documentation effort, or to produce alternatives yourself and to advertise them here or elsewhere within the Python community. But please don't come along and say Why aren't the Python docs like this other thing which happens to suit me better? TJG -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 11/02/10 10:42, jk wrote: cut Is there much chance that the Python maintainers will change their documentation system to make it more like Java or PHP? How would I go about trying to make that happen? I am by no means an authority however since you ask it here I feel compelled to give you my opinion :-) In general I would think that more documentation is always welcome, if you feel like you can make a contribution, excellent, please do! However, I found that the documentation available was enough for me, and I didn't even have to go to the googles for that. Typing help(thing_i_want_info_of) in the interpreter gives me precise consistent information for what I need to do with whatever it is I am doing and yes that is largely a replication of what is mentioned on the site itself (well more the other way around actually). In the odd cases this doesn't help me, I google for examples. If that doesn't help I look at the modules __file__ and open that module to read the source. And when I started 10 odd years ago with Python it was my first language with no prior confusion of other languages, since then I extended my knowledge with C and assembler but on a day to day basis I still use Python. -- mph -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
A tutorial type book can also be great for reference and documentation (as long as its current). I would recommend a non-programmers tutorial to python even if you have started programming in other languages before. Also its a wiki book and is free. -Braden Faulkner Sent wirelessly from my BlackBerry device on the Bell network. Envoyé sans fil par mon terminal mobile BlackBerry sur le réseau de Bell. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Tue, 2010-11-02 at 04:23 -0700, jk wrote: This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking about. Aaaarrr Why aren't the official docs like this, Because not everyone likes documentation like that. Personally I far prefer the existing documentation to the JavaDoc-style link you sent. and why has it taken me 2 days of searching? All this needs is a search engine behind it and it'd be perfect. Personally I use Google, e.g. list site:docs.python.org to bring up documentation about the list type. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Tue, 2 Nov 2010 04:23:49 -0700 (PDT) jk sanjo...@yahoo.com wrote: This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking about. Why aren't the official docs like this, and why has it taken me 2 days of searching? What's wrong with this: http://docs.python.org/library/ ? If you have specific ideas for improvements, you can open issues at http://bugs.python.org. Thank you Antoine. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Nov 2, 11:49 am, Tim Golden m...@timgolden.me.uk wrote: But why do you imagine that the core Python documentation -- developed and maintained by a group of people who clearly have some idea what they're doing -- should change to a format which happens to suit you? It's not just me who's found the current documentation frustrating. And sure, the developers know how to code, but they probably can't see the project with the eyes of a beginner any more. Making a change to how code is documented to allow more javadoc-style documentation to be produced could help people migrate from a java background and ease the learning curve for them, leading to wider adoption of the language. It wouldn't necessarily mean that the current documentation style would need to change either. In short, please feel free to contribute directly to the core documentation effort, or to produce alternatives yourself I may well do that. @Tim Wintle Personally I use Google, e.g. list site:docs.python.org to bring up documentation about the list type. Surely you shouldn't have to go to google though? Or the interpreter? Maybe it's just what you're used to, but I'd expect the language's web site to provide enough of a reference in itself, while using google for examples. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote: Hi, I've been coding in PHP and Java for years, and their documentation is concise, well structured and easy to scan. Well, that's one opinion. Others have mentioned this apparently for years (see: http://stackoverflow.com/questions/4046166/easy-to-navigate-online- python-reference-manual/4070851 and http://www.russellbeattie.com/blog/python-library-docs-still-suck and http://xahlee.org/perl-python/xlali_skami_cukta.html). Compare for instance the differences in ease of use, and speed of use, of these: http://docs.python.org/library/functions.html#open http://uk.php.net/manual/en/function.fopen.php The former is difficult to find (try searching for 'open' in the search box and see what you get). A fair point -- the built-in open comes up as hit #30, whereas searching for open in the PHP page brings up fopen as hit #1. But the PHP search also brings up many, many hits -- ten pages worth. But in any case, the Python search functionality could be smarter. If I had a complaint about the docs, that would be it. Fortunately, I have google :) It is simply a collection of paragraphs without strong enough contrast to differentiate the different parts - parameters, parameter values, return types, exceptions and related functions. It is slow to read and doesn't allow easy visual scanning. It's *nine* paragraphs, three of which are one-liners, the longest of which is eight lines. If you have trouble reading that, well, you have a problem. The PHP docs for fopen are FIFTY-EIGHT paragraphs. Okay, okay, I was unfair. I counted section headings as separate paragraphs. A more reasonable count is... twenty-six paragraphs, tables, sections and subsections. Plus *dozens* of user-contributed recipes, bug reports, tricks, tips and comments. And you call this concise??? Reading the docs, I'd say that PHP needs all this extra documentation because it's so much more complicated. fopen has all this implicit magic behaviour that needs documenting -- it will try to guess a scheme from the file name, if it can't guess the scheme it will guess that it's a local file, and the behaviour depends on various globals. In comparison, Python's open is very simple: it only opens files. No wonder Python's docs are simpler. The PHP docs felt it necessary to give a warning *three times*, one after the other, about using binary mode when opening files. Apparently once was not enough. The Description subsection of the PHP fopen doc says: fopen() binds a named resource, specified by filename, to a stream. What's a stream? So I read, and read, and read, and eventually, almost at the bottom of the official docs, I find the section Return Values: Returns a file pointer resource on success, or FALSE on error. Great! Now, what's a file pointer resource, and how does it differ from a stream? No idea. Contrast that with the Python docs. In the *very first sentence*, it says: Open a file, returning an object of the file type described in section File Objects. with both file and File Objects being hyperlinks to the appropriate part of the docs. I think I'll stick with the Python style, thank you very much. The latter has clearly delineated, standardised content areas for each of these without excessive text. It uses tables which are easy to scan for possible opening modes and allows users to contribute their own examples. There has been discussion on python-dev about user contributed examples. The pros are that users can add tricks and tips. The cons are that, without constant attention, the user-contributed content will grow old and stale, or worse, be filled with nonsense. However, there is a Python wiki. It doesn't get anywhere near as much love as it deserves, and (I think) the consensus was that the official Python docs should stay official, but link to the wiki for user- contributed content. This hasn't happened yet. http://wiki.python.org/moin/ Sadly, the use of restructured text by python doesn't allow a new document generator to be written - all existing documentation would need updating with docblocks or something similar. Has anyone else struggled while trying to learn the language? The whole documentation system seems geared towards people who already know what they're looking for and is close to useless for beginners. I'm not the only one who finds google an easier way to find documentation about python. Why do you think this is a bad thing? The Python docs are the reference manual, not a tutorial. Quite frankly, if I were a PHP developer, I'd be pretty annoyed at having to read this in the docs for fopen: If you use the wrong line ending characters when writing your files, you might find that other applications that open those files will look funny. Gosh, really? Thanks for the tip, Captain Obvious. It's always difficult to know how much information is too much. The PHP
Re: Python documentation too difficult for beginners
On 2010-11-02, brf...@gmail.com brf...@gmail.com wrote: A tutorial type book can also be great for reference and documentation (as long as its current). I would recommend a non-programmers tutorial to python even if you have started programming in other languages before. Also its a wiki book and is free. To what does it refer in the last sentence? Sent wirelessly from my BlackBerry device on the Bell network. That's nice, thank's for sharing. -- Grant Edwards grant.b.edwardsYow! Do you think the at Monkees should get gas on gmail.comodd or even days? -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Nov 2, 1:42 pm, Steven D'Aprano st...@remove-this- cybersource.com.au wrote: It's always difficult to know how much information is too much. The PHP docs seem to take an everything including the kitchen sink approach. Given that approach, it makes sense to divide everything into subsections, one page per function. But with Python's minimalist approach, it would just be annoying. Compare the four lines of: http://docs.python.org/library/functions.html#id with this re-write in the PHP fashion: = id = (Python 1.x, Python 2.x, Python 3.x) id -- id of an object Description --- id(object) id returns the numeric identity of an object, which is guaranteed to be unique and constant for this object during its lifetime. Note: two objects with non-overlapping lifetimes may have the same id() value. Note: CPython implementation detail: This is the address of the object. Parameters -- * object Any object. Note: all data in Python are objects, even ints and strings. Note: there are no undefined objects in Python. If you call id(variable) on an unbound variable name, Python will raise an exception. Return values - Returns an integer or long integer object representing the ID of the argument. Errors/exceptions - If the argument to id() is a named variable rather than a literal, and that name is not bound to any object, then a NameError will be raised. Otherwise every call to id() must succeed. Note: if the call to id() is inside a function, the exception may be a subclass of NameError such as UnboundLocalError. Note: literals are not guaranteed to always refer to the same object. Changelog - 0.9 First version added (I think). Examples id(x) id(alist[1]) id(instance.attribute) id(module.name.attribute['key'].method(arg1, arg2).seq[2]) Notes - If you're still reading, I admire your persistence. See also Python's object model Exceptions Steven You're right in that the python docs in this case are less lines, but that's one of the problems. It doesn't mention anywhere the extra detail you've added regarding exceptions thrown. That's the kind of thing that probably comes through experience or some kind of convention which isn't obvious to beginners. Having things split into sections - parameters, return types, exceptions, etc - lets me find what I'm looking for quickly. As for the 9 paragraphs statement, there's a usability book that applies here - it's called Don't make me think. I shouldn't have to go through freeform text to find what I'm looking for when a list would make that information easier to find. And splitting the docs into sections would allow me to skip to what I'm looking for. I really would be much happier with your example documentation. I think the key difference is that I don't want to have to *read* the python docs - I want to be able to scan for what I'm looking for and find it easily. That makes me productive. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
Steven D'Aprano st...@remove-this-cybersource.com.au writes: A fair point -- the built-in open comes up as hit #30, whereas searching for open in the PHP page brings up fopen as hit #1. But the PHP search also brings up many, many hits -- ten pages worth. OTOH googling for python open gives you the correct (for 2.7) page as hit #1 - although you then have to use your browser's find facilty to actually get to the description of the function in question. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
jk a écrit : Hi, I've been coding in PHP and Java for years, and their documentation is concise, well structured and easy to scan. Others have mentioned this apparently for years (see: http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851 and http://www.russellbeattie.com/blog/python-library-docs-still-suck and http://xahlee.org/perl-python/xlali_skami_cukta.html). Totally unrelated, but the last example is nothing but a reference - xahlee is one of the worst internet troll ever. Compare for instance the differences in ease of use, and speed of use, of these: http://docs.python.org/library/functions.html#open http://uk.php.net/manual/en/function.fopen.php Sorry but as far as I'm concerned, PHP doc sucks big time, and I find Javadoc-style stuff close to useless. (snip) Has anyone else struggled while trying to learn the language? Not as far as I'm concerned. I found Python the easiest language to learn right from the beginning. Not to say the doc couldn't be improved, or that alternate documentations could help, but I never had any problem with it. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 11/2/2010 6:42 AM, jk wrote: Compare for instance the differences in ease of use, and speed of use, of these: http://docs.python.org/library/functions.html#open http://uk.php.net/manual/en/function.fopen.php The former is difficult to find (try searching for 'open' in the search box and see what you get). duh. 'open' is a common word and if you make an unstructured search for it in all text, you should get a lot of hits. The Python docs have both a Global Module Index (which I use constantly) and a General Index of functions (methods), classes, and terms. Learn to use them. If you look in the [o] section for 'open', the first entry is open() (built-in function) -- just what you were looking for. There are also about 30 more nicely labelled entries for 'open' in various modules. It is simply a collection of paragraphs without strong enough contrast to differentiate the different parts - parameters, parameter values, return types, exceptions and related functions. It is slow to read and doesn't allow easy visual scanning. It is possible that this particular entry could be improved. Is there much chance that the Python maintainers will change their documentation system to make it more like Java or PHP? There are plans to make doc feedback from users easier. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 02/11/2010 14:47, jk wrote: I think the key difference is that I don't want to have to*read* the python docs - I want to be able to scan for what I'm looking for and find it easily. That makes me productive. Hi jk, I totally agree. But you will get nowhere. A few weeks back I complained that http://docs.python.org/reference/executionmodel.html#naming-and-binding was more than a little opaque - and was not understood by Python noobs such as myself. I was invited to rewrite it and submit an improved version. Remember I said I was a noob and did not understand it. Just how can I rewrite it from that base? But I'm sure that the trouble is with me. It is clear from this statement (rom that page)... If a name binding operation occurs anywhere within a code block, all uses of the name within the block are treated as references to the current block. that, (in the given situation), name binding does not bind a name to a variable but to a block. /sarcasm Just for the record, I really know it is not me. English is my mother tongue, and I have some programming experience, in a variety of languages. I wrote my first program in 1964, and have been earning a living programming since '74. I have used Cobol, Lisp, Smalltalk, C, Javascript, Notes, PHP and many other languages in a commercial environment over the last 36 (good gracious!) years. This lack of documentation is almost universal. You will have heard of the with batteries tag. This means that, whatever you want to do, there are usually many libraries available to help you do it. Every one will be poorly documented and most are hard to find. Yes there are batteries - but it is not clear which is more productive: write what is needed from scratch, or investigate what batteries are available and risk finding that the one you chose is missing some important feature down the line? Observe though that having poor introductory documentation sells a lot of How to Program in Python type books. Its sad really. Python is a great little language, and deserves better. Without an on-ramp, noobs will struggle to get on the freeway. And yet, enough will get on, that these pleas for better documentation can be ignored by those who know and could do something about it. Regards Ian -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 2010-11-02, jk sanjo...@yahoo.com wrote: As for the 9 paragraphs statement, there's a usability book that applies here - it's called Don't make me think. I shouldn't have to Anything that promotes a lack of thinking sends up red flags in my head. We want to recruit smart people who think, not idiots. go through freeform text to find what I'm looking for when a list would make that information easier to find. And splitting the docs into sections would allow me to skip to what I'm looking for. I really would be much happier with your example documentation. ctrl-f will bring up a search dialog in most graphical browsers. '/' will in many others. With some practice, your fingers will be able to find something far faster then your eyes can see it happen. There is a religious war in the GNU community between info page as documentation versus the traditional manual format. The manual format contains all of the information on one page that can be easily searched whereas the info pages are split into sections that must be viewed individually. With the man pages, you can almost always find what you want with a quick search through the document. Info pages are much harder to use because you have to try and figure out which section the author decided to place the information that you are looking for. The information may be stored several levels deep, which means that it can be a deep productivity hit if you don't guess the proper location on the first try. I think the key difference is that I don't want to have to *read* the python docs - I want to be able to scan for what I'm looking for and find it easily. That makes me productive. The real question is what do you want to gain by your posts here. You should already know that most groups are, by their very nature, slow to make changes to the status quo. The problem tends to be exasperated in open source projects where any changes mean that people have to donate their time to make anything happen. You will in general find two things to be true: 1. Since they are dontating their time, you will find that people tend to scratch their own iches first. 2. People who do take the time to contribute to open source projects are people of action. They don't tend to be appreciative of those who constantly generate feature requests but have no inclination to do any of the work themselves. They do appreciate other people of action who are interested in making the project better. Therefore, if you truly want changes in the documentation, I suggest that, rather then whining to the group, you make some of the changes yourself. When you are finished, you can post a link to your alternate documentation to this group. If you documentation is truly better then the existing documentation, you will not have to say another word. People within the community will rally around it and promote it. If it gains wide enough support, then there will be a movement to use it to supplant the existing documentation. It is the difference between whining from the sidelines and actively participating in the game. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Nov 2, 8:47 am, jk sanjo...@yahoo.com wrote: You're right in that the python docs in this case are less lines, but that's one of the problems. It doesn't mention anywhere the extra detail you've added regarding exceptions thrown. That's the kind of thing that probably comes through experience or some kind of convention which isn't obvious to beginners. Having things split into sections - parameters, return types, exceptions, etc - lets me find what I'm looking for quickly. It doesn't mention it because those exceptions don't actually have anything to do with the id() function. They're just what happens any time an unbound variable name is evaluated, in any context. The exact same thing could be said about any Python function in existence that takes at least one argument. Cheers, Ian -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 11/2/2010 7:53 AM, Paul Rudin wrote: Steven D'Apranost...@remove-this-cybersource.com.au writes: A fair point -- the built-in open comes up as hit #30, whereas searching for open in the PHP page brings up fopen as hit #1. But the PHP search also brings up many, many hits -- ten pages worth. OTOH googling for python open gives you the correct (for 2.7) page as hit #1 - although you then have to use your browser's find facilty to actually get to the description of the function in question. Right. Google does a far better job of organizing Python's documentation than the Python community does. I don't even try looking up anything starting at Python.org; I always start with a Google search. Even though Python.org's search is powered by Google, it's inferior to a general search. Compare: http://www.google.com/search?domains=www.python.orgsitesearch=www.python.orgq=open http://www.google.com/search?q=Python+open John Nagle -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Nov 2, 2010, at 11:07 AM, Ian wrote: On 02/11/2010 14:47, jk wrote: I think the key difference is that I don't want to have to *read* the python docs - I want to be able to scan for what I'm looking for and find it easily. That makes me productive. Hi jk, I totally agree. But you will get nowhere. A few weeks back I complained that http://docs.python.org/reference/executionmodel.html#naming-and-binding was more than a little opaque - and was not understood by Python noobs such as myself. I was invited to rewrite it and submit an improved version. In this world of moderated wikis one would think that noobs such as myself could enhance the docs when we find something confusing in the docs. insert snarky comment here Kee -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 03/11/10 05:04, John Nagle wrote: Right. Google does a far better job of organizing Python's documentation than the Python community does. I don't even try looking up anything starting at Python.org; I always start with a Google search. Even though Python.org's search is powered by Google, it's inferior to a general search. Compare: http://www.google.com/search?domains=www.python.orgsitesearch=www.python.orgq=open http://www.google.com/search?q=Python+open Even better: http://www.google.com/search?sitesearch=docs.python.orgq=open Regards, John McMonagle -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 11/2/2010 2:43 PM, Tim Harig wrote: The real question is what do you want to gain by your posts here. You should already know that most groups are, by their very nature, slow to make changes to the status quo. The problem tends to be exasperated in open source projects where any changes mean that people have to donate their time to make anything happen. You will in general find two things to be true: 1. Since they are dontating their time, you will find that people tend to scratch their own iches first. 2. People who do take the time to contribute to open source projects are people of action. They don't tend to be appreciative of those who constantly generate feature requests but have no inclination to do any of the work themselves. They do appreciate other people of action who are interested in making the project better. Therefore, if you truly want changes in the documentation, I suggest that, rather then whining to the group, you make some of the changes yourself. I agree up to here, with a different interpretation of the last clause. Work within the existing system. There are currently 250 open doc issues on the tracker at bugs.python.org. After registering, go to the search page http://bugs.python.org/iss...@template=searchstatus=1 select Components: Documentation and hit Return (or [Search]) Find an issue that is waiting for someone to suggest a new or replacement sentence or paragraph, and make one. No .diff patch required, just put it in the message. Or look at existing suggestions and comment. -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On 2010-11-02 10:42:22 +, jk said: Hi, I've been coding in PHP and Java for years, and their documentation is concise, well structured and easy to scan. Are you mad? Javadoc is one of the worst examples of source code documentation I can possibly imagine. I would go as far to say that the Python guys should do exactly the opposite of Javadoc. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
In message a5dc65e1-3a72-4160-90e3-956a456be...@26g2000yqv.googlegroups.com, jk wrote: This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking about. Framesets? Is that really your idea of well-laid-out documentation? Using a feature which has been derided (and dropped in HTML5) because of its effect on usability and accessibility? -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Nov 3, 7:43 am, Tim Harig user...@ilthio.net wrote: On 2010-11-02, jk sanjo...@yahoo.com wrote: As for the 9 paragraphs statement, there's a usability book that applies here - it's called Don't make me think. I shouldn't have to Anything that promotes a lack of thinking sends up red flags in my head. We want to recruit smart people who think, not idiots. Don't make me think is the UI equivalent of There should be one and preferably only one obvious way to do it. Not about advocating no thinking, but about reducing the amount of unimportant decisions you require your users to make. But I don't think the book specifically addresses Dutch users though. Back on topic - I do like the Python docs overall. Especially compared to the PHP docs. I like the overall look and format of the new Sphinx generated ones too. My only criticism is that the content can sometimes be a little too terse/concise. It's fine for experienced developers, but in some places a little more explanation and/or examples would help out the less experienced. I can usually figure out how to do something eventually, but the docs for some modules take more deciphering than others. -- Cheers Anton -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
On Wed, Nov 3, 2010 at 9:05 AM, Nizumzen nizum...@mcnuggets.com wrote: Are you mad? Javadoc is one of the worst examples of source code documentation I can possibly imagine. I would go as far to say that the Python guys should do exactly the opposite of Javadoc. For what it's worth, I concur. cheers James -- -- James Mills -- -- Problems are solved by method -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
Therefore, if you truly want changes in the documentation, I suggest that, rather then whining to the group, you make some of the changes yourself. I agree up to here, with a different interpretation of the last clause. Work within the existing system. There are currently 250 open doc issues on the tracker at bugs.python.org. wow, a backlog of 250. Either 250 is the weekly submittal amount and they get dealt with within a week, OR the backlog is months old and the bug system is not an effective way to get changes or enhancements to the documentation. Either way, 250 open doc issues gives me the feeling that the existing documentation system is not working for the people trying to use it. After registering, go to the search page http://bugs.python.org/iss...@template=searchstatus=1 select Components: Documentation and hit Return (or [Search]) Find an issue that is waiting for someone to suggest a new or replacement sentence or paragraph, and make one. No .diff patch required, just put it in the message. Or look at existing suggestions and comment. Given that newbies are the ones who run into these issues and have a great desire to spare others the pain they have suffered trying to learn Python, and newbies typically do not know about the bug tracking system as the way to request enhancements to the docs (that's not how wikipedia and other sites do changes to information), perhaps it would be useful to put a link to a page that explains how to improve the docs, on each doc page? I have to agree with others. My preferred Python documentation is either the books I have, or a search on Google. A google search typically has several postings from people on non-official sites with the exact same confusion I have, and what they have tried and what ultimately worked. The suggestion was made that people create their own documentation if they don't like the official documentation, and that does seem to be a good source for python documentation. Kee Nethery -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
In message 2010110223050345181-nizum...@mcnuggetscom, Nizumzen wrote: On 2010-11-02 10:42:22 +, jk said: I've been coding in PHP and Java for years, and their documentation is concise, well structured and easy to scan. Are you mad? Javadoc is one of the worst examples of source code documentation I can possibly imagine. It appeals to corporate herds of code-cutter drones, though. It follows tedious rules that can be officially adopted as corporation policy, and cited as a conformance feature by third-party products that these corporations seem happy to spend money on. So the comments can be extracted from the code, sorted, collated, stamped, filed, indexed, and collated again, all as part of the make-work activity that seems to pass for actual productivity in so many big corporations. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
My 2c: I use the ActiveState distro, and it's winhelp doco. It's generally ok and some things, like Dive Into Python, I've found excellent. But I do quite regularly find myself cursing at the vagueness of the index, and some of the content seems to require that you know it before you read it (I wish I could remember an example). Like everything, it could be improved. Cheers, JB -- http://mail.python.org/mailman/listinfo/python-list
Re: Python documentation too difficult for beginners
AD i agree with you! The official python tutorial and the official docs are pretty much a twisted mass of confusion to the initiated programmer. Even today when i try yo search the docs i find the result quite frankly useless. And the search reminds me of the old XP puppy dog search. The doc ARE fairly well written HOWEVER the search engine needs an update. For me, i just Google it, and forget it! -- http://mail.python.org/mailman/listinfo/python-list
