> -----Original Message----- > From: [EMAIL PROTECTED] [mailto:python- > [EMAIL PROTECTED] On Behalf Of Antoon Pardon > Sent: Tuesday, April 24, 2007 7:40 AM > To: python-list@python.org > Subject: Re: Tutorial creates confusion about slices > > On 2007-04-24, Michael Bentley <[EMAIL PROTECTED]> 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 -- http://mail.python.org/mailman/listinfo/python-list
