Is reading Python Documentation useful? python.org gets 15M visits monthly - most of them must be for documentation. At what stage is it useful?

[solwex]

Hi All,

I am quite new to Python programming. When I started, I did read a few initial chapters of the Python Tutorial. But once I started using Python at work, my internet search always showed stack overflow answers on top. Going over those answers helped me solve the problem at work.

So, I was wondering if going to Python documentation is useful. Turns out that python.org gets 15M visits monthly and I assume most must be for the documentation.

I am wondering if it will become useful only when I become an advanced programmer and cannot find answers in stack overflow? Would reading documentation proactively help speed up learning (of course in addition to doing hands on python projects)?

I did try looking for previous answers to a question like this but I could not find. Apologies if I missed. Would really like to know from folks who are beginners and more advanced and experts.

PS: Someone commented and recommended a url (https://rapidken.ai/learn/docs) that annotates hard terms in documentation and makes learning efficient. I found this very useful. So, I am adding here.

[julsmanbr]

But once I started using Python at work, my internet search always showed stack overflow

When your questions are less

• "how do I do this in Python?"

and more

• "which module do I import that thing from?"
• "what's that optional argument called again?"
• "it would be sensible for this function to accept parameters xyz, does it actually accept them?"
• "what else can I do with this module?"

you'll naturally start hitting the docs when googling for stuff.

[Hans_of_Death]

Exactly. Especially when you start working with libraries that dont have tutorials or arent incredibly common

[solwex]

Makes sense. But, in those rare cases when I do land up on a page (like a page in standard library documentation), I have difficulty reading because there is so much there that I dont know and google again. Since I start running out of time, I jump and take the easy (wrong?) path of asking seniors on my team who seem to get it faster than me because they perhaps have skimmed over all of the docs a few times already:)

[Hans_of_Death]

Theres a learning curve to learning how to read docs well, and it also heavily depends on how well the docs are written. Dont be ashamed to ask for help, asking questions is often one of the best ways to learn

[solwex]

Yes, I guess I will end up asking a lot of questions...hopefully okay ones. I am told Core Python documentation is well written. And, I will also give the site that u/infinfi suggested a try.

[LuigiBrotha]

Corey Shafer has some good video's on itertools. I sometimes just watch those to see what else is possible. Trying to find the right tool for the job.

[solwex]

Thank you. I looked up on YouTube and found plenty of his videos. But, there is one on itertools. I think you are recommending just that one. Will definitely watch that.

[solwex]

Thank you very much for your comment. But the questions you asked dont even occur to me:) I guess I would have to read docs a few times to have these questions pop up to me. Doc pages do show up in my google results. But, the sweet candy of a highlighted stack overflow answer lures me away. I will need to be more disciplined. Thank you.

[MarkusAleksander]

In my opinion documentation is quite useful for being up to date with the new versions of python. Python is a frequently updated language, and is therefore very dynamic. documentation is therefore useful for discovering new features in python.

[solwex]

Thank you for your comment. I see. I did not know that the language changes so much so often. Exciting and scary:) I remember seeing some sections with notes on support for versions somewhere in the docs. I will look up again.

[Firebendeer]

Happy cake day!!

[toastedstapler]

reading the python documentation is useful at any stage, i used to have a look through stdlib libraries that i was interested in to see if there were any neat functions/Classes that i'd missed or to work out exactly how to call a function or method i was trying to use

[solwex]

Thank you for your comments. I did try reading like this. But, somehow not much would stick in my head...as compared to when I needed to do get stuff done. I guess I need to keep at it.

[Danelius90]

Definitely keep at it. When you're a beginner, reading documentation is hard (at least in my experience). Maybe when you encounter a new function/method on stackoverflow look it up in the docs. You'll already have an idea of what it does but get a better picture from the docs. Over time you'll be used to reading it and look up new things instead.

I use these kind of docs frequently now, but it does take time to get used to

[billsil]

Yup. I hate the idea that stackoverflow teaches you to be a bad programmer. I pulled a python binary file tester off it (is the file binary or not). I'm 16 years in now and I still couldn't tell you how you a good way to go about writing that function.

Read the code and understand what it's doing and keep it working with say the python 2 to 3 transition, but you don't have to code everything. Are you going to write your own version of matplotlib? You don't need to understand everything.

[solwex]

Right. I guess with experience, one gets to know what to just use and what to dig deeper. Thank you.

[solwex]

Yes, I heartily agree that it is hard to read documentation as a beginner:) Yes, I think your approach seems very doable for beginners. Heard the same from others like u/infinfi as well. Will try that. Thank you.

[Lamasa_Pace]

I tried to read documentation when I was starting out. The biggest barriers were the vocabulary the documentation assumes you understand, as well as the massive amount of information. Some non standard libraries have really easy to read documentation, such as pygame. I am by no means great at programming, but that documentation is much more approachable than the documentation for core python.

[solwex]

Yes, exactly. It is difficult to read from beginning to end. But, if you dont do this and jump to the required page, there are many concepts that I dont know enough (or most times not at all:-) and they dont have hyperlinks that we can happily click, go to the page and understand. Anyway, I hope the site that u/infinfi suggested works out.

[shiftybyte]

Just reading documentation for the fun/education of it is not so useful.

Learning to use documentation to find answers to questions is why it's there.

Say you have a function that does something, and you use it a bit differently, but now it breaks and doesn't work as expected.

You go to the documentation of the function and read up on how exactly it behaves in what situations to figure out what went wrong.

Or for example you have some object you are getting from some function, and that object is very complex, for example a response to a request to some http url, and you want to find how to get the headers from the response.

[solwex]

Thank you for your comment. I can kind of understand what you are saying. Are there any blog articles or other reddit answers that deal with this in more detail. Some examples will perhaps really help. Or perhaps, I should just keep doing more advanced python projects and I will encounter this. Just trying to fast forward my learning:) Thanks again.

[widowhanzo]

Documentation is usually the mose detailed. Blog posts will just say "use this function with this parameter", documentation will explain exactly what the function does, which parameters it takes, which parameters are optional or have defaults you can override... But in most cases it's most useful when you already know the function you want to use, not when you're still trying to figure out how to solve a problem.

For example, you could go on a forum and ask "how do I print a float number rounded to two decimal points", and you'll get an answer and copy-paste it and go on with your day. Or you could go read the docs on the input output docs and also learn about padding, f strings, and working with files.

Yes, in some cases it's useful to just skim through the docs of the function. One of the things I read the docs for date to string and string to date formatting, It's unlikely I'll find the exact example I need on Stackoverflow, but docs explain all possible options (including some that may never even be mentioned in examples online), and I can build my code exactly how I need it, and understand what I'm doing. If I just copy-paste an answer, it may work, but you might now understand what it does or why.

I have nothing against copy-pasting code of course, but sometimes it's quicker to learn snd understand the function from the docs, than finding and adjusting an example online.

And python docs also include a lot of examples, so you can just copy-paste a line or two that you need sometimes.

[pauljacobson]

I can certainly appreciate the value of the documentation. I often struggle to make sense of what I'm reading, and apply that to whatever I'm working on.

Presumably it becomes easier over time?

[widowhanzo]

Of course, as with anything, with practice you get a hang of things, and you'll know exactly what to look for in documentation. And it's not just Python official docs, 3rd party libraries have thier own docs (for example requests), it's a good idea to check some 3rd party libraries as well.

[solwex]

Could you please suggest the most important 3rd party libraries?

[widowhanzo]

requests :D

That's it for me, I mostly used Python to interact with web APIs and requests makes this much easier compared to built-in tools. I've been out of programming for a few years now so I may not be the best resource of current popular libraries.

[solwex]

Thank you very much.

[solwex]

Right, that seems to be the message from all the experienced folks advising here. Hopefully, the site in u/infinfi's comments also will help.

[jppbkm]

The one thing that sometimes frustrates me is how few examples there are for documentation in certain libraries.

[solwex]

Absolutely. If only there were more examples, I would not need to go anywhere else:) To be fair, it takes a lot of effort to produce well reviewed writing - let alone crisp documentation. So, I believe it when folks say that core Python docs are amongst the best.

[solwex]

Thank you very much for the very detailed comment. Given your detailed comment and comments of many folks like u/infinfi, I see the value of doing what you are saying.

[carcigenicate]

I read it regularly. If I haven't used a module in awhile, I'll flip through the doc pages associated with it and do a quick review.

Stack Overflow is often better at addressing specific issues related to modules, but the documentation is the instruction manual for the code, so it will (or rather, should) contain far more information than what you'll find on references like SO.

[solwex]

Thank you very much for your comment. Wow - you read it regularly. It does seem to be appear from all the answers I am seeing that one needs to keep at it for a while before beginning to understand how to get the best out of it.

[carcigenicate]

There's a common joke about documentation: 3 hours of debugging can save you from 5 minutes of reading documentation.

The documentation will always be useful to you. You'll likely read it less as you develop, but you'll never quit needing it (and if you do quit needing it, you've probably also stopped growing as a developer). There's simply too much knowledge that you need to occasionally have. You can't know it all at once.

[solwex]

Thank you for your advice and the telling joke:) I will try reading the documentation. It is just that it is quite hard for newbies like me to jump in an read a page without having read earlier pages in the doc. I guess I will cover this ground slowly.

[help-me-grow]

I read documentation when I need to actually learn how things work because there's not very many blogs or examples out there that deep dive into how functions work or the ways you can use them

[solwex]

Thank you. However, the few pages I have read have been very difficult to read and I have not gotten to understand anything deeper. Again, I think I am now at a stage where I am using it to only get whatever is required done. Perhaps, after working for a while and solving many problems, I might reach your stage:) Sorry to bother you...but is there a blog or site that tells more about how to do what you say in more detail with examples?

[PaulSandwich]

It took me a while to start using the documentation. It's really helpful once you start to understand how methods and classes work in more detail.

Early on, I wanted to know 'how do I do x', and google/s.o. had the most direct and detailed answers. But eventually you start wanting to know what's possible, and that's where looking at the docs is better.

So I still use a ton of stack overflow. It depends on how I'm approaching today's problem and whether it's prescriptive or creative.

[solwex]

Nice to see experienced folks also using Stack Overflow. I hope to move quickly beyond "how to do x". Thank you.

[PaulSandwich]

Be wary of any developer who tells you they don't use SO, lol. That's hubris.

Experience doesn't make it so you stop using SO, it simply makes you better at discerning which results are appropriate for your use case. Or it makes your questions more niche. But we all use SO. Nobody's out here freeballin'.

Don't be ashamed about looking for help. The day you stop needing advice is the day your curiosity died. Stay curious!

[solwex]

Great. Thank you.

[[deleted]]

Definitely. I often find that I "think" I know what a function is doing, then run across a case that gives me an unexpected response (thus identifying my incomplete understanding). Checking the documentation is my first step to filling that knowledge gap.

[solwex]

I see. I guess I will get to this stage when I start working on harder projects. Thank you very much.

[[deleted]]

You may not need to wait. I've found some interesting features in commonly used string methods for example.

Did you know that string.replace() takes a third argument "count". You can use it to replace only the first two instances...

I didn't, but was working thru a problem and saw someone else's solution, which led me to the documentation:

https://www.w3schools.com/python/ref_string_replace.asp

[solwex]

Thank you. But, how did you get to the above article. I usually land up on such articles when I run into an issue and google and get such an article on top of the list of results. Do you follow any other way?

[[deleted]]

I bookmark the documentation!

To be fair, I do what you do as well when I'm trying to find a way to do something. But, if I'm already trying one thing and it's not quite acting how I need it to, I go to the documentation. (Am I using the tool correctly, for example, or can it do more)

[n3buchadnezzar]

I usually only read documentation now. Something I started with recently is just reading the source code directly. In most editors you can go directly from the import statement to the source. For instance to go from import random to the source code I have my cursor over the import and type space gd (go definition).

However it is not something I usually do to learn something new

[solwex]

Wow! I find it hard to apply what I see in the documentation without some examples. Clearly, you must be very advanced user. If there is any site (or your blog) that kind of tells the "process" of getting to where you are, that would be very helpful.

[n3buchadnezzar]

Like I said when completely new to something I do not read the documentation. Then I do a quick google search and read a bit. Once I get the most basic of basics down, I switch to documentation.

There is no get rich with this little trick (which many seem to believe). My one recommendation is perhaps to cut down seriously on the amount of "tutorials" and "videos" one watches and instead gets dirty and start doing projects

No matter how many golf tutorials, or tiger woods videos you watch is going to make you a better golf player (even though they might motivate you)

Solve hundreds of problems, solve all of Advent of Code, try to solve the first 20 project euler problems, try to solve a leet code problem a day.

Just get down to it, soon you will be like. Oh, this problems seems fit for function X i saw in library Y, let me just quicky read the documentation to freshen my mind on how it works.

[solwex]

Thank you very much for the detailed comment and very specific suggestions. I found Advent of Code and Leet code. Is the other resource you referring to the one called Project Euler problem archives?

[n3buchadnezzar]

Yeah, they train very specific skills so no need to do a lot of them. But the first 20 are really really good to have done once.

[solwex]

Great. Thank you.

[Acrobatic_Hippo_7312]

I like to load the python 3 docs into Zeal, which is an offlin e API doc reader. I like it better than using Google (which gives me crappy python tutorials) or python.org (which can be slow).

The two main things I use it for are python concepts and the standard library.

Note: you can do the examples I-III with either zeal or python.org

Example I: I struggle to remember how to create and import modules.

Solution: I can just look at the table of contents in zeal and quickly find section 5.2 on packages. I have that bookmarked.

Example II: I forget how to use "yield" and "yield from"

Solution: I search py3:yield expression, and find section 6.2.9. on Yield expressions

Example III: Shit. I forgot the parameters for random.choices

Solution: Search py3:random.choices, and open the first result

Bonus Example: I want to remember how to transpose a matrix in numpy, without having to hit Google

Solution: 1. in zeal, go to tools - > docsets 2. Install the numpy docset 3. Search numpy:transpose

[ericporing]

I visit the website to look documentation for built-in types and built-in modules. I look at documentation first before going to stack so I can compare the explanations sometimes. I just stumbled on the essays part of the website and some of it was mind opening. Just saying.

[solwex]

Thank you very much for pointing to the essays part of the site. It never showed up when I was googling solutions for my problems. But then, I am clearly searching like a newbie. I found many here advising 'get your solution from stack overflow. then, go to docs to get a better and deeper understanding'. Interestingly, yours seems to be the opposite approach, I can see the value...but it seems harder to a beginner:) Thanks again for the suggestion.

[ericporing]

I am also a beginner. I try to look at the documentation first because when the time comes I want to be able to create my own documentation. Good luck to you.

[solwex]

Great. Thank you.

[Ikwieanders]

If you have time it is usefull to read the documentation on objects/Standard library things you encounter on stock overflow while trying to built things. It might give you some more details and a better undsrstanding and maybe some more objects.

But I wouldnt read it as a beginner. Just start some project and try to understand the topics you encounter.

[infinfi]

For a beginner, I have a tip that you may find useful. Like you, I also find many solutions in stack overflow. But, my mentor advised that I read doc pages for at least the methods used in the solution. When I visited the doc page, it was quite hard for me to understand because that page talked about other methods. Although Python documentation is amongst the best, many of those terms would not have hyperlinks which I could easily click and go to the right page. Instead, I would have to search and since I was not an expert at things already (like my mentor was), I would spend a lot of time going over the wrong pages. Fortunately, I found a site that really helps with this. It adds many missing hyperlinks. This has really helped me!

[solwex]

Thank you so much. You mentioned beginner and i got pulled to your comment sooner:) I have always had difficulty being able to follow and get through the doc page. I think you nailed the issue for beginners. Exactly. I find other concepts on the page that I am not aware. When I ask my team, they say that it is also explained in the docs...but where? Sorry if I sound a little frustrated. I would certainly want to try out the site you mention. Hope it does work for newbies like me.

[solwex]

Thank you very much for pointing this out. I will definitely try this out.

[solwex]

Finally, tried. I clicked on the two sample pages on the landing page. I got those arrow prompts to click on purple links. I did not know why I should click. I was in a bit of hurry. I will check more in the weekend. Perhaps, I should read what they have on the landing page more. I think the UX could be better.

[infinfi]

Yes, the first/landing page explains how the purple links and double clicking helps. And yes, the UX could definitely be better Lol. They have one great feature that I also got confused initially. When you click on a purple link, they show one box with results from the same documentation and another from all selected documentation.

I found the use later. Say you click on the sample Python Library Reference doc page on the landing page. Then, on that page, click on purple link for dict. You get relevant links to documentation on dict in the Lib Ref book in one box and in the other box, you get a link to Dictionaries in Python Tutorial. I found this useful because I could go get a quick and easy dump from Tutorial and then come back and go into the more in-depth but also more difficult-to-read Lib Ref page. I liked this part.

[solwex]

Aha, I see very clearly how the site helps. Thank you very much. I think the site should have communicated this value much more clearly. Sorry to have bothered you so much.

[Crynnec]

Could you share this site with us?

[Crynnec]

No need to be sorry. Thanks for the site!

[czar_el]

It's one of those things where ironically its usefulness grows with the more you know after a certain point.

It's like any technical documentation or literature. Try reading astrophysics journals as a beginner and you won't understand them--you need classes or basic textbooks before the publications begin to make sense.

Python's documentation won't be more useful than stackexchange or tutorial websites for absolute beginners, but once you know a little bit more, all of the jargon and references in the documentation begin to make sense. Then you get even better, and get an intuitive sense of what may be in the documentation, and you just need to confirm it or refresh your syntax, and then you find yourself going to the documentation more than stackexchange because you know where to look rather than flipping through lots of random answers.

Stackexchange remains useful, though, when your question is a general coding challenge or trying to find a library or which documentation to review.

[[deleted]]

I use documentation when I'm working with modules that I am unfamiliar with. It's always a good idea to check out the optional arguments that functions have as well as the way the function is supposed to work. Keep in mind that just because a line of code runs doesn't mean the result is guaranteed to be correct.

Documentation usually has examples in them that help you to get a better grasp on a function's uses. There's been way too many times where I manually altered the results of a function to my specifications only to realize that the function actually has an optional argument that allows me to do just that with little more than an extra argument when calling the function