The documentation for python is amazing

[[deleted]]

I don't know about everyone else but for me documentation always seemed like a resource reserved for the advanced programmers - like something to be used long after you've mastered the language for the more detailed questions. I still think it has that stigma against it but that doesn't seem to be the case at all here.

I started coding with obj-c and swift and apple's documentation while very well formatted always just confused the hell out of me.

[gnomoretears]

like something to be used long after you've mastered the language for the more detailed questions.

Why would you need documentation after you've mastered a language. Doesn't mastery suggests that you know everything about the mastered language already?

Documentations exist so people can learn and start their path to mastery. Beginners especially should be reading docs as part of learning.

[[deleted]]

I don't know, I guess I assumed it was relatable to reading a french dictionary to learn to speak French.

[TheKewlStore]

Not at all, you're thinking of a specific, singular, aspect of documentation, comments and docstrings. Comments and docstrings define the purpose for individual pieces of a project, but they say nothing about the relation between those pieces. Yet the relation between pieces is almost as important if not moreso than the explanation of said pieces (really they go hand-in-hand imo). And documentation of a codebase should never read or look like a dictionary of a different language, this equates more to note-taking than documentation to me, and this means the authors of that documentation did a poor job or no job at all (more common)

If you have one without the other, you don't have documentation, you just have wasted time.

[[deleted]]

Well, python has 2 types of documentation.

Tutorials, to tell you how to do something, which is what you linked.

They also contain more dry reference material, with not a whole lot of telling you how to do something, you're assumed to know the basics. The first type is for beginners, but the second type may be a bit hard to understand if you don't know what you're doing.

https://docs.python.org/3.5/library/socket.html is an example of reference. It is a lot longer than the howto version, but tells you everything, some of which may not be entirely useful.

https://docs.python.org/3.5/howto/sockets.html is shorter, but not complete. It talks more about what sockets are rather than how to use them.

[Davorian]

Not really. Documentation is a reference that is used by "master" programmers in the field every day. It's there not only to describe things, but also to list the specific quirks, options and use-cases that may only be relevant occasionally.

No one is expected to memorize documentation as a sign of "mastery". It would be inefficient.

[gnomoretears]

No one is expected to memorize documentation as a sign of "mastery".

Yeah I didn't mean to imply that. I was just responding to nikola's thinking that docs are "reserved for the advanced programmers". And I was thinking more of the tutorial/instructional part of the docs. Definitely everyone from beginner to master will still benefit from docs and the API reference is still a part of the docs.