Tutorial creates confusion about slices

[Hamilton, William]

> -----Original Message-----
> From: python-list-bounces+whamil1=entergy.com at python.org
[mailto:python-
> list-bounces+whamil1=entergy.com at python.org] On Behalf Of Antoon
Pardon
> Sent: Tuesday, April 24, 2007 7:40 AM
> To: python-list at python.org
> Subject: Re: Tutorial creates confusion about slices
> 
> On 2007-04-24, Michael Bentley <michael at jedimindworks.com> wrote:
> >
> > On Apr 24, 2007, at 6:35 AM, Antoon Pardon wrote:
> >
> >> People don't read tutorials in a strictly linear fashion. They can
> >> continue to later subjects and then come back here to see how
things
> >> tie together. So the fact that it is only confusing to those who
> >> know more than is already presented doesn't seem a very good reason
> >> to leave it in.
> >
> > Yet they understand that earlier in the document, there is likely to
> > be a less complete coverage of a given topic.  There is in fact, a
> > link on that page that includes a more complete coverage of that
> > topic (which I mentioned to you in an earlier message IIRC).
> 
> That there is more complete coverage elsewhere is no good reason
> to come with an explanation that suggests things working in
> a way that will be contradicted by that more complete coverage.
> 
> Even after people have read the more complete coverage it is
> still very possible that they will come back to this part of
> the text and get the wrong idea of how things work.

That's how everything I've ever learned has been taught.  Start with a
simple explanation that may not be completely accurate but is
functional, then fill in the details later when there is a context to
put them in.  The tutorial could start out by explaining everything at
the implementation level; it doesn't because it is a _tutorial_,
intended to give new users the context they need to understand the more
complicated nuances of the language.  

If it covered every fiddly little detail, it wouldn't be a tutorial.  It
would be a language reference document instead.

> A more complete coverage elsewhere is not an adequate remedy
> for a tekst suggesting things working differently than they
> actually do. Sure in the long run people will figger out how
> things actually work and that the explanation given in that
> section is totally inadequate for negative steps. But I
> prefer that people don't loose too much time figgering out
> that a particular explanation only works for particular cases
> and not in general.
> 
> > Submit a patch if you want it changed.  I'm sure your valuable
> > insights will greatly improve the quality of the python
documentation.
> 
> Fat chance, if they reason like you.

So you're saying your insights aren't valuable?


---
-Bill Hamilton