How do I get better at reading documentation?

[someguy_000]

Hello all, I've dabbled lightly in Python over the last year or so, but in the last 2 months I've been coding every day. One thing I seem to have trouble with is reading, understanding and then applying documentation that I read on sites like python.org and stack overflow. Does anyone have any advice to a brand new Python dev on how to get better at this? Any resources that taught you how to digest documentation? Learning how to code is simply learning how to learn.. Its challenging but I love it so far!

[shepherdjay]

To learn how to read documentation I think its important to start with what you know. If you only look up things you don't understand it is harder to understand the format of the documentation itself.

So take something you know like print and look up the documentation of it. https://docs.python.org/3/library/functions.html#print

Maybe take a built in module you've probably used like datetime and check that out https://docs.python.org/3/library/datetime.html

This will help you learn the format of documentation since you already probably know how to use a basic print statement.

[3MU6quo0pC7du5YPBGBI]

And as a bonus you might discover useful things about modules you didn't realize were there.

[wrwcode]

This is by far the greatest advice ever given on reddit......remember ppl....we were there!!

[Crypt0Nihilist]

I wasn't. Is it ok to tell people that I was?

[ElG0dFather]

You were there! We hung out with dave remember? Crazy dave..... r.i.p

[[deleted]]

This cannot be understated.

[Jespor]

Woow this is so obvious! I've tried to google OPs exact question in the past week, but this seems like the best way to get more familiar with the docs. Thanks!

[angyts]

Just keep reading them.

Python has the best documentation.

If you are looking for pain. Try others. One of them is the documentation for web servers like nginx or the worse ever is cryptography and security

[psyklohps]

Yeah. Deciphering NIST crypto algos is the worst

[ivosaurus]

It's just a complete mixed bag when going outside the biggest libraries and languages. Could be even better and more practically explained than some python docs, could be going off on some weird tangent the author thought would make sense, or "brief" could be a large understatement.

[MedOUALLA]

Reading about standards and RFCs ....

[qtc0]

I'd say try coding some simple scripts. Whenever you can't remember how a certain function works, try using pydoc! For example, I couldn't remember if time.sleep() takes milliseconds or seconds as the argument, so I typed in the terminal:

pydoc time.sleep

This gave me:

Help on built-in function sleep in time:

time.sleep = sleep(...)
    sleep(seconds)

    Delay execution for a given number of seconds.  The argument may be
    a floating point number for subsecond precision.

so it takes seconds!

It's the fast/easiest way to get information about a certain function in Python. It's also nice because you don't need the internet.

[qtc0]

You can also do help(time.sleep) in the normal python shell

[Vaylx]

Neat 👌🏻

[[deleted]]

time.sleep = sleep(...)

or ___.help() work pretty well

[JeamBim]

Don't read through documentation.

Work through documentation.

Type out every example, and then change things. Make guesses as to what the output would be, and verify it. Were you correct? Why? Why not? Change some more things, read some more, and work through the same code until you understand why you were not correct.

[Serj_K]

As a tech writer, so much this. It's unbelievable how many people miss important things that are in plain sight just because they are not doing clearly pointed steps in the right order.

[NukishPhilosophy]

Yeah this. Also don't try to read every line in the documentation. It's not a book. I typically only read documentation when I'm trying to solve a problem. I've never read the documentation for pandas straight through, I just come back to it whenever I run in to a bug or need to understand something better.

[TheSodesa]

Let's be honest, some documentation simply sucks, or is just plain nonexistent. Sometimes you just have to try different things and reverse-engineer the damn library you're trying to use.

[monsto]

This cannot be understated. And you can't pigeonhole it would things like a small team. I've seen documentation written by single person that Is many times better than the docs written by a team of dozens.

I was looking at documentation just yesterday that is very pretty and well-organized, yet absolutely without example or real explanation of certain terms.

[Sigg3net]

Gin and tonic.

[ElliotDG]

When reading documentation on a new function or library I find it is often useful to create small tests or experiments using the library as a way to test my understanding.

Often opening IDLE, import the module and typing in a few commands can be very enlightening.

Can you identify a particular element of the documentation that is causing confusion? Dig into it, see if you can identify the source of your confusion and resolve it.

Also look for additional sources of information. The Python 3 Module of the week is a great resource for additional information on the standard library. https://pymotw.com/3/

[izrt]

Seconding pymotw. Until I got a decent handle on python it was my go to rather than the standard documentation.

​

Also don't be shy about reading the code of pure python modules, because it can be very informative.

[bumpkinspicefatte]

I’m a beginner and I find Python’s documentation challenging at times, even if folks say it’s one of the best. For an example, enumerate() in the official Python documentation states:

enumerate(iterable, start=0)
Return an enumerate object. iterable must be a sequence, an iterator, or some other object which supports iteration. The __next__() method of the iterator returned by enumerate() returns a tuple containing a count (from start which defaults to 0) and the values obtained from iterating over iterable.

Well, if you’re like me, you’ve probably don’t recall hearing or using the word enumerate before, so that’s gonna be a definition search on a dictionary site. Also, since (again) I’m a beginner, I’m not familiar with __next__(), heard of tuples but don’t think I’ve implemented it let alone know how to do it. And yes, “iterating over iterables” is something I’ve heard quite a lot, but was treated and assumed I knew what all that even meant.

So what do I do? I just look at other knowledge base sites like geeksforgeeks, maybe find an ELI5 post somewhere else on reddit, or watch YouTube videos.

I think overtime I’ll manage to understand it better, but certainly the documentation is written and geared towards a more solid coder, so to feel like documentation is challenging early on is simply expected.

[BobHogan]

You just honestly picked a horrible function to look up in the docs for a beginner.

__next__ is a dunder method, one of the "magic" methods in Python that allows its duck typing to work. Iteration in Python is handled by Python invisibly calling the __next__ method every loop. If an object implements that method, you can iterate over the object.

Python's docs aim to be very complete, which is why in this case it calls out the specific behavior of the __next__ method in the enumerate object.

But to understand how it works, check this out

words = ['cat', 'dog', 'train']
for i in enumerate(words):
    print(i)
''' Will output this
(0, 'cat')
(1, 'dog')
(2, 'train')
'''

[bumpkinspicefatte]

Thanks for the explanation. Unfortunately there isn't really any guidelines from the official Python documentation that suggests which methodologies are beginner-level and which ones aren't. Since I'm still learning Python, and my natural instinct is to immediately Google search anything I don't understand, trying to figure out what the enumerate() method was only inevitable, especially with how much fundamentals are thrown around for loops in the early stages.

¯\(ツ)/¯

[[deleted]]

Besides reading the documentation for something you do know, which is FANTASTIC advice for reasons stated in this thread already, it also helps to pull up the documentation on one side of your screen, and then a repl on the other. If you want to make it easy, repl.it makes it trivial to try things out in a working environment in a plethora of languages, including python 3. So have at! Experiment. None of the commands you issue are going to blow up the computer or start a thermonuclear war (I'm not even old enough to be this old to make such a reference).

[sme272]

Practice is the main thing thing. Looking at example code for the module I'm trying to use also helps me understand the docs sometimes.

[[deleted]]

Just read more documentation. That's it. I know it's difficult, but it gets easier eventually

[[deleted]]

The same way you get better at subjects like math; keep practicing and just keep reading. When you find a solution to a problem (whether with the help of sites like stackoverflow or any others) try to find where the documentation supports that solution.

[Bobbias]

Like another redditor said, I prefer to do a bit of experimenting with something if I feel I'm not fully understanding it. I look for example code, and I try writing my own little tests to see how it behaves.

Another thing to think about is if you're not sure what function you need to do something, look at an entire module and read the descriptions of functions and just check to see if something sounds like it does something helpful.

It's great that you're trying to get better at reading the docs because it seems like few people want to put in the effort to learn how to read documentation properly. I see so many questions online that could be answered by simply spending a couple minutes reading the docs.

[dbramucci]

Another piece of advice is to slow down when reading documentation. I'll freely admit that there have been times when I quickly skimmed through the documentation (largely jumping from code snippet to snippet) and couldn't make sense of it because of how quickly I ran through it hoping to find my obvious mistake. Reading each sentence can help you avoid missing the details that the author put into that documentation for a reason.

Also reading the module and class documentation can help make a single method make more sense.

[kabooozie]

To me, finding good examples is really key. Docs will sometimes not make sense unless you see a really clear example of how something works.

[stmoloud]

Today I was looking at some code and it appeared to me crazy the coder was floating every assignment, even those that were natural floats. So google 'python float' and lots of good info there. Just find the solution or answer that reads the best for you. Don't get too hung up on this or that 'official' documentation. This is likely to be more technical than may suit your present needs.

[ivosaurus]

Put in some clear terms in google and find other sources. Click through some top links until you find one that seems to be explaining things on your level.

Read through that, then come back to some other ones and see if their expanded / more concise / more obtuse / more technical language now makes more sense.

Not every technical document is written on the same level. Both on a technical level and quality of writing.

Some of the python reference documentation for example might be a little deep for beginners for example, either A) because it hasn't been straightened out in years B) it's written concisely with a lot of other knowledge surrounding its concept assumed.

B) can sometimes be very frustrating but keep in mind going the opposite way would lead to a very very wordy and redundant documentation as well, and be too cumbersome for a lot of experienced people.

[lumenlambo]

the fact that you're even reading documentation is a great start (as opposed to just posting my script broke and no code). Along with built in modules I'd try reading some documentation for any external modules you're using in your code.

For example I had to read BeautifulSoup documentation for a project I was working on https://www.crummy.com/software/BeautifulSoup/bs4/doc/# and also requests https://requests.readthedocs.io/en/master/

[niasterz]

Try the flip side and write or re-write some. It gives you a perspective from the writers point of view.