Python's official docs do a good job with this approach too, I think. The Python Language Reference is relatively easy to read for a lay-man when that's necessary, and includes the formal logic of the spec in little call-out boxes -- but it's also accompanied by the Python Tutorial, which manages to cover nearly everything while making no attempt to get into every edge-case and obscure method, keeping it focused and readable. It's a great learning tool to get up to near-proficiency, and then the Reference is there for all those little "but I wonder what happens when..." questions.
What even does "the list of methods" mean? Do you mean the builtins? Those are at the docs for built in functions.[1] Or do you mean the list of all functions? Because that doesn't exist for the very good reason that it doesn't make sense to have a list like that for python. There's the module index[2] though which lists every available module, linking to their docs which list all the available functions in those modules.
Having a single list of all functions in python makes very little sense for the simple reason that you'd not be able to find what you're looking for in that list so you might as well just use the search in the first place.
Side note: if there's a specific function you'd like to get the documentation for you can get that easily from the interactive python prompt with the "help" function:
>>> help(zip)
And I fail to see the "missing examples". While it's true that most modules don't contain examples for every single function they usually contain a few examples for the overarching concept.
So which part exactly of the python docs is bad? IMO they are, by far, the best docs any programming language has.
Yes, I realize I can use help. Does it being available in one place mean that it shouldn't be available in others? If I'm in an IDE I don't always have the command prompt in front of me, and that should be fine!
Some context: the page documenting lists [0] is the same page that documents all* Python's built-in types; lists are documented in section 4.6.4, where section 4.6 is titled "Sequence Types — list, tuple, range".
Many operations on a list are much the same as the methods on a tuple, so they are documented in one place – section 4.6.1 "Common Sequence Operations" – rather than duplicated in both the list and tuple documentation. Similarly, many of the methods supported by list are also supported by bytearray, so they are documented in 4.6.3 "Mutable Sequence Types" rather than duplicated. To get from the section on lists to the two sections describing the available methods involves pressing page-up twice. Hardly "strewn across three different location", and there's always help(list) if you really want a list of every supported method.
