4 ms·

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 un

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?

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?