[nonzero]

I wish programming documentation in general were divided into two heavily linked parts, one conversational introductory section and one concise and technical reference section (like a manpage). By heavily linked, I mean the "conversational" section should have plenty of links to the reference section inline with the prose and vice versa. I don't like reading references when I don't even see the big picture. On the other hand, I don't like getting too used to intro material because it's too verbose to refer to later. But if the conversational part has links to the reference section and vice versa, I would get into the habit of following the links and gradually familiarizing myself with the layout of the reference section. Unfortunately, as it is, intros rarely have these links or footnotes to the references, and I have to search for items specifically, losing out on the holistic view.

[Goladus]

Intro material, even if it's not too verbose, may omit important details anway. For example, a regex tutorial might only give a brief, vague explanation of raw strings (maybe a quick comment about not needing to escape backslashes, etc.). Eventually you'll want to read the more comprehensive reference on string literals, to make sure you haven't missed anything. (In the case of raw strings, unicode characters are still escaped and you can't end one with an odd number of backslashes.)

http://docs.python.org/reference/lexical_analysis.html#strin...