I don't want to argue your example too much, because I understand that you wanted something simple to illustrate your main point. However, being as I am someone in the same boat as you when it comes to things like syntax of less-frequently used aspects of Python, I do want to point out a fourth option, which, for me, would actually be the first option: docs.python.org.
For things like straight syntax questions, I find it is the most efficient.
I have found that I can save a few more seconds by creating a search shortcut in Firefox (details upon request), which would let me get the answer, in this example, by typing Ctrl-L, py enumerate, Enter.
I think that would color-code, following your scheme, to almost all blue, and the non-blue part would be due solely to the fact that the documentation for enumerate() only takes up half a screen.
I completely agree with you about using the official docs, and how that would code in this analysis. The search that inspired this post was for a CSS rule I hadn't used before, and I didn't know a specific place to go for that, but I knew I'd spot the correct syntax in just about any source that mentioned it. That's how I ended up on these kinds of SEO-overoptimized sites again.
I think it takes most people a while to become comfortable using the docs. They're a reference (https://diataxis.fr), and many people need to use more explanatory sources for a while before they're comfortable using reference sources. I think this applies even when looking up specific syntax. For example, I can read the enumerate() docs and get the information I need from seeing what's returned by list(enumerate()). But if someone needs to see an example that uses enumerate() in a for loop, they need to look outside the docs.
Jan 25, 2023·edited Jan 25, 2023Liked by Eric Matthes
I agree about the docs being a little forbidding to people who are just getting started, particularly as far as the paucity of examples goes. (In fact, I sometimes toy with the idea of writing examples aimed at beginners and offering them to the Python docs team.)
That said, I think it is good to try to develop the habit of taking a quick look there first, even if one has to look elsewhere, say, for examples. Getting good at reading (good) documentation is a as big a part of improving one's ability to program as anything else I can think of.
Also, as you note, many other sources near the top of typical Google results can be frustrating, for a variety of reasons; e.g., too simplistic (maybe doesn't show all possible args to enumerate()), too cluttered with noise, and so on. And there is also the risk, especially on SO, of encouraging copypasta code that seems like it solves the problem, but may mislead or otherwise not convey a solid base of explanation.
Finally, I agree that it can be hard to find what one wants in the docs in the case you mentioned: "I know it's *something* like this, but ..." In that case, it is amazing how often and how well it works to just start typing one's best guess into Google. Here, in your case, where you were actually looking for something other than the syntax for enumerate(), it certainly applied.
Thanks for the response. And for the posts, in general.
I don't want to argue your example too much, because I understand that you wanted something simple to illustrate your main point. However, being as I am someone in the same boat as you when it comes to things like syntax of less-frequently used aspects of Python, I do want to point out a fourth option, which, for me, would actually be the first option: docs.python.org.
For things like straight syntax questions, I find it is the most efficient.
I have found that I can save a few more seconds by creating a search shortcut in Firefox (details upon request), which would let me get the answer, in this example, by typing Ctrl-L, py enumerate, Enter.
Either way, here's where I'd end up:
https://docs.python.org/3/library/functions.html?highlight=enumerate#enumerate
I think that would color-code, following your scheme, to almost all blue, and the non-blue part would be due solely to the fact that the documentation for enumerate() only takes up half a screen.
I completely agree with you about using the official docs, and how that would code in this analysis. The search that inspired this post was for a CSS rule I hadn't used before, and I didn't know a specific place to go for that, but I knew I'd spot the correct syntax in just about any source that mentioned it. That's how I ended up on these kinds of SEO-overoptimized sites again.
I think it takes most people a while to become comfortable using the docs. They're a reference (https://diataxis.fr), and many people need to use more explanatory sources for a while before they're comfortable using reference sources. I think this applies even when looking up specific syntax. For example, I can read the enumerate() docs and get the information I need from seeing what's returned by list(enumerate()). But if someone needs to see an example that uses enumerate() in a for loop, they need to look outside the docs.
I agree about the docs being a little forbidding to people who are just getting started, particularly as far as the paucity of examples goes. (In fact, I sometimes toy with the idea of writing examples aimed at beginners and offering them to the Python docs team.)
That said, I think it is good to try to develop the habit of taking a quick look there first, even if one has to look elsewhere, say, for examples. Getting good at reading (good) documentation is a as big a part of improving one's ability to program as anything else I can think of.
Also, as you note, many other sources near the top of typical Google results can be frustrating, for a variety of reasons; e.g., too simplistic (maybe doesn't show all possible args to enumerate()), too cluttered with noise, and so on. And there is also the risk, especially on SO, of encouraging copypasta code that seems like it solves the problem, but may mislead or otherwise not convey a solid base of explanation.
Finally, I agree that it can be hard to find what one wants in the docs in the case you mentioned: "I know it's *something* like this, but ..." In that case, it is amazing how often and how well it works to just start typing one's best guess into Google. Here, in your case, where you were actually looking for something other than the syntax for enumerate(), it certainly applied.
Thanks for the response. And for the posts, in general.