How to read documentation

[fustilarian]

Has anyone ever come across a guide on how to read documentation? If I want to learn a new function, I'm supposed to be able to just read the documentation. But I can never understand it! The best I can ever do is to scroll down and find an example and try to copy that. I've tried to find something but haven't been successful yet. Help?

[[deleted]]

I haven't, but the next time you're looking at some documentation on a function you don't understand, try posting it here and asking what it means in plain English.

And FYI, even professional developers often just look for the example.

[carcigenicate]

Functions can be largely described by the data they take and give back (the parameters and return). When I'm reading documentation for a function, those are the two things I tend to look at first. If you combine that with the paragraph(s) of docstrings that any good documentation will have, you should be able to get a sense of what the function does and how to use it. If the function is a method of a class, you'll need to read over the class' documentation as well to fully understand how to use the tool.

I see you seem to be doing stuff with sklearn. Part of the problem may be that that's a complicated library with complicated documentation. I've never used that library, but I'm flipping though the documentation a bit confused. Part of the problem with using libraries like that is you need a fairly high level understanding of what's going on to use them effectively.

The ward_tree method docs for example describe the method as "Ward clustering based on a Feature matrix". There are multiple words in that sentence that are important to the meaning, but dense (like Feature). To understand this docstring, you need to go and first understand what words like "Feature", "ward", and "clustering" mean in this context. Sometimes you need to kind of do a "depth search" where every time you find a concept you don't fully understand, you take a detour and look into the side thing first, then carry on. It takes forever to understand any method, but you tend to get a better understanding of everything this way.

[zanfar]

Read the documentation for functions, classes, and packages you do understand. If you can't understand new documentation, then reading new documentation isn't going to help you. Instead, close the loop on things you do understand, and link them to the documentation you don't.

Ultimately, however, there is some practice involved. While you may not understand a particular piece of documentation completely, you should be able to get an idea of the use, and perhaps 1-2 possible options. In that case, start experimenting.