23 ms·

Quoting myself from a blog post i wrote when i was learning Python two and a half years ago [1]: Let’s say i want to know how to do the Python equivalent of PH

by huskyr 10y ago

Quoting myself from a blog post i wrote when i was learning Python two and a half years ago [1]: Let’s say i want to know how to do the Python equivalent of PHP’s foreach. The docs about the for statement say this: The for statement is used to iterate over the elements of a sequence (such as a string, tuple or list) or other iterable object: for_stmt ::= "for" target_list "in" expression_list ":" suite ["else" ":" suite] Right, so what does that mean? What’s ::=? What’s an ‘expression list’? The expression list is evaluated once; it should yield an iterable object. An iterator is created for the result of the expression_list. The suite is then executed once for each item provided by the iterator, in the order of ascending indices. “Ascending indices”? “Suite”? This might be clear for a CI professor, but it’s not for the mere mortals that read the docs and want to get stuff done. Things haven't gotten much better since then. [1]: https://www.haykranen.nl/2014/02/12/saying-hello-to-python-some-observations/ https://www.haykranen.nl/2014/02/12/saying-hello-to-python-s...

jacobolus 10y ago
You were reading the wrong docs for a newbie. The language reference is intended for people who want a very concise and precise technical document, not an introductory explanation. If you read the very beginning, the language reference is very clear about what it is and isn’t: > This reference manual describes the syntax and “core semantics” of the language. It is terse, but attempts to be exact and complete. The semantics of non-essential built-in object types and of the built-in functions and modules are described in The Python Standard Library. For an informal introduction to the language, see The Python Tutorial. You should have been looking at the Python Tutorial instead. https://docs.python.org/3/tutorial/controlflow.html https://docs.python.org/3/tutorial/controlflow.html https://docs.python.org/3/tutorial/datastructures.html#looping-techniques https://docs.python.org/3/tutorial/datastructures.html#loopi...
- jawbone3 10y ago
  Another nice example of what the author complains about, a "it's your own fault" reply whenever someone complains that the official language docs are hard to understand. Personally I almost never find any use from the docs whenever they come up in a google search, its almost as bad as those expert-exchange hits that used to appear. The core issue being that pythons docs are only a language reference for the vast majority of the standard library, and the size of the stdlib bein one of pythons strengths.
  - makomk 10y ago
    Personally, as a 16 year old (or possibly younger, it was a long time ago) with no internet connection and little programming experience I found the Python user documentation very helpful. That possibly had something to do with me actually reading the tutorial rather than dismissing it as beneath me or ignoring it altogether and attacking the person who brought it up.
    - jawbone3 10y ago
      Well, the discussion is about the docs recently available online, so you finding a python book helpful in the times when no python shell autocompleted is a bit outside the topic at hand.
      - makomk 10y ago
        I'm talking about exactly the same documentation and the same tutorial that's available online (well, obviously it was a much older version of it). Only difference is that the offline version is a directory of local HTML files rather than a website. The user experience is pretty much the same with both. Still pretty handy even in the StackExchange era, though it'd be more useful if Google didn't keep finding the wrong version of the docs (2.x when I'm using 3.x or vice-versa).
  - jacobolus 10y ago
    It’s not “it’s your own fault”, but rather “you should read the document you’re looking at, and think critically, instead of expecting that every google hit is going to be precisely what you are looking for right off the bat, with no need to scroll or read”. If the author had gone on the Freenode #python IRC channel or the Python Users mailing list (or..., or...) and asked “Hi, I’m a newcomer trying to understand Python loops, what’s the best resource?” someone could have linked him to the tutorial. Or if he’d done a google search and tried skimming a few hits, he would have found it. It’s hopeless to expect that every single document in the world will be tailored for every reader. There’s a real value to a concise and precise technical document aimed at folks who need something closer to a specification than to an introductory explanation. It would be net-negative to remove the language reference from the internet, or clutter it up with a bunch of information that can easily be written somewhere else. Imagine someone wanted to understand the basics of how levers and pulleys work, and they came across a quantum mechanics textbook, which wasn’t comprehensible at their current level of understanding. Should the reader blame the book, or keep looking for a more appropriate source?
- huskyr 10y ago
  Sure, in a perfect world i would read the complete tutorial before i get started on a new language. But it's not a perfect world, i want to get stuff done. I have twenty years of programming experience, i don't need to learn what a for loop is (the first link) and i don't want to read a whole document just to find a reference to the items() function (second link). I just want to know what the equivalent of foreach() is in Python. Sure, a document with a 'very concise and precise' technical description might be useful to some, just for looking up things it's not. The current alternative is Googling StackOverflow posts.
  - junke 10y ago
    Sure, in a perfect world the documentation would guess who I am and adapt accordingly, be both highly detailed when I need it or informal when I don't. But it's not a perfect world, I want to get stuff done. I have twenty years of programming experience, I know how to find the information I need. Sure, the whole language explained in one place for all kind of people from beginners to experts would be nice. But I have Internet. I type "foreach python" in Google and I see a StackOverflow post.
    - lawpoop 10y ago
      > I type "foreach python" in Google and I see a StackOverflow post. That's kind of indicative right there.
      - junke 10y ago
        Indicative of what? Are you trying to say that a the docs should have "Python for X programmers" sections, foreach (no pun intended) X in {Perl, PHP, Haskell, Lisp, Go, Javascript, C++, ...}? That would be nice, but what is even better is a totally different resource that aggregates idioms for all languages: https://www.rosettacode.org/wiki/Loops/Foreach https://www.rosettacode.org/wiki/Loops/Foreach
        lawpoop 10y ago
        That the first result is a stackoverflow question about the language rather than a documentation page, is indicative that getting started with the language is not so straight-forward, even factoring in documentation. If you're googling 'python foreach', you're probably at the beginner level, and the fact that a documentation page is not the first result means that the beginners documentation is not very discoverable. The fact that there's a not-closed, highly-upvoted, highly-ranked stackexchange question about this very basic issue in existence /at all/ is what one might call a "documentation smell".

by huskyr 10y ago

jacobolus 10y ago

You were reading the wrong docs for a newbie. The language reference is intended for people who want a very concise and precise technical document, not an introductory explanation. If you read the very beginning, the language reference is very clear about what it is and isn’t: > This reference manual describes the syntax and “core semantics” of the language. It is terse, but attempts to be exact and complete. The semantics of non-essential built-in object types and of the built-in functions and modules are described in The Python Standard Library. For an informal introduction to the language, see The Python Tutorial. You should have been looking at the Python Tutorial instead. https://docs.python.org/3/tutorial/controlflow.html https://docs.python.org/3/tutorial/controlflow.html https://docs.python.org/3/tutorial/datastructures.html#looping-techniques https://docs.python.org/3/tutorial/datastructures.html#loopi...

jawbone3 10y ago
Another nice example of what the author complains about, a "it's your own fault" reply whenever someone complains that the official language docs are hard to understand. Personally I almost never find any use from the docs whenever they come up in a google search, its almost as bad as those expert-exchange hits that used to appear. The core issue being that pythons docs are only a language reference for the vast majority of the standard library, and the size of the stdlib bein one of pythons strengths.
- makomk 10y ago
  Personally, as a 16 year old (or possibly younger, it was a long time ago) with no internet connection and little programming experience I found the Python user documentation very helpful. That possibly had something to do with me actually reading the tutorial rather than dismissing it as beneath me or ignoring it altogether and attacking the person who brought it up.
  - jawbone3 10y ago
    Well, the discussion is about the docs recently available online, so you finding a python book helpful in the times when no python shell autocompleted is a bit outside the topic at hand.
    - makomk 10y ago
      I'm talking about exactly the same documentation and the same tutorial that's available online (well, obviously it was a much older version of it). Only difference is that the offline version is a directory of local HTML files rather than a website. The user experience is pretty much the same with both. Still pretty handy even in the StackExchange era, though it'd be more useful if Google didn't keep finding the wrong version of the docs (2.x when I'm using 3.x or vice-versa).
- jacobolus 10y ago
  It’s not “it’s your own fault”, but rather “you should read the document you’re looking at, and think critically, instead of expecting that every google hit is going to be precisely what you are looking for right off the bat, with no need to scroll or read”. If the author had gone on the Freenode #python IRC channel or the Python Users mailing list (or..., or...) and asked “Hi, I’m a newcomer trying to understand Python loops, what’s the best resource?” someone could have linked him to the tutorial. Or if he’d done a google search and tried skimming a few hits, he would have found it. It’s hopeless to expect that every single document in the world will be tailored for every reader. There’s a real value to a concise and precise technical document aimed at folks who need something closer to a specification than to an introductory explanation. It would be net-negative to remove the language reference from the internet, or clutter it up with a bunch of information that can easily be written somewhere else. Imagine someone wanted to understand the basics of how levers and pulleys work, and they came across a quantum mechanics textbook, which wasn’t comprehensible at their current level of understanding. Should the reader blame the book, or keep looking for a more appropriate source?
huskyr 10y ago
Sure, in a perfect world i would read the complete tutorial before i get started on a new language. But it's not a perfect world, i want to get stuff done. I have twenty years of programming experience, i don't need to learn what a for loop is (the first link) and i don't want to read a whole document just to find a reference to the items() function (second link). I just want to know what the equivalent of foreach() is in Python. Sure, a document with a 'very concise and precise' technical description might be useful to some, just for looking up things it's not. The current alternative is Googling StackOverflow posts.
- junke 10y ago
  Sure, in a perfect world the documentation would guess who I am and adapt accordingly, be both highly detailed when I need it or informal when I don't. But it's not a perfect world, I want to get stuff done. I have twenty years of programming experience, I know how to find the information I need. Sure, the whole language explained in one place for all kind of people from beginners to experts would be nice. But I have Internet. I type "foreach python" in Google and I see a StackOverflow post.
  - lawpoop 10y ago
    > I type "foreach python" in Google and I see a StackOverflow post. That's kind of indicative right there.
    - junke 10y ago
      Indicative of what? Are you trying to say that a the docs should have "Python for X programmers" sections, foreach (no pun intended) X in {Perl, PHP, Haskell, Lisp, Go, Javascript, C++, ...}? That would be nice, but what is even better is a totally different resource that aggregates idioms for all languages: https://www.rosettacode.org/wiki/Loops/Foreach https://www.rosettacode.org/wiki/Loops/Foreach
      - lawpoop 10y ago
        That the first result is a stackoverflow question about the language rather than a documentation page, is indicative that getting started with the language is not so straight-forward, even factoring in documentation. If you're googling 'python foreach', you're probably at the beginner level, and the fact that a documentation page is not the first result means that the beginners documentation is not very discoverable. The fact that there's a not-closed, highly-upvoted, highly-ranked stackexchange question about this very basic issue in existence /at all/ is what one might call a "documentation smell".