[Python-Dev] The socket HOWTO

"Martin v. Löwis" martin at v.loewis.de
Mon Jun 6 10:23:18 CEST 2011


>  > Did you run a user survey?
> 
> Martin undoubtedly has a lot of experience with users, and it's quite
> reasonable for him to express his opinions based on that informal
> sample, yes.

In particular, this is collected experience from interaction with
students learning Python, or other languages. When they try to solve
a problem, they don't read specification-style documentation. Instead
they look for examples that they can imitate.

[I notice that you (Stephen) also confirmed this from your own
 experience]

> The issue here is the difference between existential and universal
> quantifiers.  Martin's arguments are not inconsistent.  They simply
> acknowledge the existence of subsamples of users of the same document
> with different needs and/or approaches to reading the document.  He
> does not and has never claimed that all of his arguments apply to all
> of the potential readers.

Exactly so. I'd like to settle this discussion based on the anecdotal
report of several users on this list that they considered the
tutorial useful.

> You might question whether the same document should serve both the
> "cargo cult the examples" group and the "read the fine print" group.
> That's a valid question, but here my feeling is that the answer is
> "yes".  I very often "cargo cult" my first program, then go back to
> the fine print and experiment by gradually changing that program to
> test my understanding of the detailed explanations.  It is often
> easiest to use the same document for both purposes because I already
> know where it is and the quality of the writing.

In that spirit, I'd be in favor of removing outright errors from the
document, and overly subjective and argumentative passages. Other
than that, I still think its fine as it stands.

Regards,
Martin


More information about the Python-Dev mailing list