3 ms·

I think this is the exact type of comments that the author comes out against. You aren't putting yourself in the shoes of a beginner. Let's say I'm a beginner

I think this is the exact type of comments that the author comes out against. You aren't putting yourself in the shoes of a beginner. Let's say I'm a beginner, and I want to just experiment with the language a bit (I've already read some tutorials or am not interested) - since I'm just trying to get the feel of the language and ecosystem, I'm not trying to get a deep understanding of the language and tools - I want to match a regex. In the C++ and PHP examples he provided, the basic example is easily found - it's basically two actions - search in google and scroll to the example. What you are suggesting takes several more steps - ctrl-f for a text that you might get wrong (you've searched for sample instead of example for instance), iterate until you get the right place, etc... And that's assuming you even realize that you should run ctrl-f, why should you? The main issue though is that if I'm a beginner I'm doing this kind of searches several times a minute - to have to stop and realize what to look for every time is extremely frustrating. I've worked with Ruby,Python, Java and Javascript - python's (and django's) documentation is extremely verbose and rarely straightforward compared to the other ones.

junke 10y ago
> You aren't putting yourself in the shoes of a beginner. How do you know if I am putting myself in the shoes of a beginner or not? And what kind of beginners are we talking about? Are they comfortable with a browser? Do they already know how to program something? You can't expect a single document to be relevant for all kind of people. The reference documentation has a clear target audience, which apparently conflicts with what you expect from it. > And that's assuming you even realize that you should run ctrl-f, why should you? > (you've searched for sample instead of example for instance) Okay, so you are talking about absolute beginners, with no experience whatsoever with programming. And the C++ and PHP pages are somewhat useful for them? > I've already read some tutorials or am not interested > Let's say I'm a beginner [...] I want to match a regex. Now, you are saying that you already have experience with programming? Google "python tutorial regex" gives plenty of results, the first of them being currently "Regular Expressions HOWTO" (https://docs.python.org/2/howto/regex.html https://docs.python.org/2/howto/regex.html). Absolute beginners need a teacher, a mentor, or a step-by-step book, or a very gentle tutorial, or an online REPL. That's fine. You can't please everybody in the reference documentation.
- userbinator 10y ago
  And what kind of beginners are we talking about? Are they comfortable with a browser? Do they already know how to program something? I'll add to that, "Are they even computer-literate in any way?" I'd worked at a college a few years ago, and it is sometimes shocking how little the newcomers know about just using and troubleshooting basic problems with computers, nevermind learning how to write programs for one... and IMHO it's only gotten worse. Knowledge of things like basic filesystem concepts ("What's a directory? How do paths work?") in particular seem to be disappearing.
ubernostrum 10y ago
You aren't putting yourself in the shoes of a beginner. The real issue you and the author both run into is assuming that the wants, needs and learning styles of all people everywhere are identical. There's a good argument to be made for expanding the variety of styles and types of documentation available in order to cater to more ways of learning, but not a good argument to be made for suppressing or removing existing documentation since that boils down to "all right, let's cut off those people to focus on these people". One big example that's not covered, but relevant, is how many (free, so potentially competing with the author's book) workshops or online complete guides to learn Python or Python-related tools have been popping up the past couple of years. Having an experienced coach who walks you through everything your first couple of days and gets you acclimated is a huge deal for some people (while others prefer to read on their own in an undirected way), but isn't accounted for in the article.

junke 10y ago

> You aren't putting yourself in the shoes of a beginner. How do you know if I am putting myself in the shoes of a beginner or not? And what kind of beginners are we talking about? Are they comfortable with a browser? Do they already know how to program something? You can't expect a single document to be relevant for all kind of people. The reference documentation has a clear target audience, which apparently conflicts with what you expect from it. > And that's assuming you even realize that you should run ctrl-f, why should you? > (you've searched for sample instead of example for instance) Okay, so you are talking about absolute beginners, with no experience whatsoever with programming. And the C++ and PHP pages are somewhat useful for them? > I've already read some tutorials or am not interested > Let's say I'm a beginner [...] I want to match a regex. Now, you are saying that you already have experience with programming? Google "python tutorial regex" gives plenty of results, the first of them being currently "Regular Expressions HOWTO" (https://docs.python.org/2/howto/regex.html https://docs.python.org/2/howto/regex.html). Absolute beginners need a teacher, a mentor, or a step-by-step book, or a very gentle tutorial, or an online REPL. That's fine. You can't please everybody in the reference documentation.

userbinator 10y ago
And what kind of beginners are we talking about? Are they comfortable with a browser? Do they already know how to program something? I'll add to that, "Are they even computer-literate in any way?" I'd worked at a college a few years ago, and it is sometimes shocking how little the newcomers know about just using and troubleshooting basic problems with computers, nevermind learning how to write programs for one... and IMHO it's only gotten worse. Knowledge of things like basic filesystem concepts ("What's a directory? How do paths work?") in particular seem to be disappearing.

ubernostrum 10y ago

You aren't putting yourself in the shoes of a beginner. The real issue you and the author both run into is assuming that the wants, needs and learning styles of all people everywhere are identical. There's a good argument to be made for expanding the variety of styles and types of documentation available in order to cater to more ways of learning, but not a good argument to be made for suppressing or removing existing documentation since that boils down to "all right, let's cut off those people to focus on these people". One big example that's not covered, but relevant, is how many (free, so potentially competing with the author's book) workshops or online complete guides to learn Python or Python-related tools have been popping up the past couple of years. Having an experienced coach who walks you through everything your first couple of days and gets you acclimated is a huge deal for some people (while others prefer to read on their own in an undirected way), but isn't accounted for in the article.