[docs] Improve the "introduction" page of the tutorial (issue 14097)

rdmurray at bitdance.com rdmurray at bitdance.com
Wed May 8 14:23:56 CEST 2013


On 2013/05/01 22:50:41, ezio.melotti wrote:
>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode110
> Doc/tutorial/introduction.rst:110: Complex numbers are also supported;
imaginary
> numbers are written with a suffix
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > The problem with completely omitting this is that the 'j' notation
is a
> special
> > feature of the syntax, unlike Decimal or Fraction, which are "just"
> specialized
> > classes.
> 
> This could go in a footnote.

Because it is part of the language syntax I think there should be at
least a one line mention in the main text.  It could then have a 'for
more information' link.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode551
> Doc/tutorial/introduction.rst:551: object!  We'll come back to *object
> semantics* later.
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > On 2013/04/02 01:19:18, ezio.melotti wrote:
> > > This is a fundamental concept, and this lighthearted introduction
only
> serves
> > to
> > > add more confusion IMHO.
> > > I removed the example for now, but this should be covered at a
later point.
> > 
> > I think maybe you could (should) cover it at an *earlier* point, in
the
> > discussion of [:] and what makes it a copy.
> 
> I think this should be presented in the second page, so that people
can first
> digest what they learned here.
> If we put this at the end of the page they might end up reading it
while their
> brain is still overheating from the amount of information they just
learned and
> risk to misunderstand it.

That seems fine, if you also move the [:] example to that page.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode76
> Doc/tutorial/introduction.rst:76: 
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I know this is early in the tutorial, but should divmod be mentioned
here?
> 
> Maybe in a footnote, functions haven't even be introduced yet, and
divmod() is
> not really common.

Probably even a footnote isn't appropriate.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode77
> Doc/tutorial/introduction.rst:77: With Python is also possible to use
the ``**``
> operator to calculate powers::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > "With Python it is also", but I'm not sure why "also"?  It doesn't
seem to be
> > related to the discussion of division.
> > 
> 
> Most of the other languages only provide the 4 basic operations, but
Python also
> provides **.

Without having created that context for 'also' in the text, I think it
would
be better to just drop it.

> > The other problem with introducing ** here is that any discussion of
** should
> > include a discussion of operator precedence and why -1**2 == -1.
> 
> That's too advanced/specific for now, I think it could be explained
somewhere
> else if necessary (or maybe in another footnote?).

A footnote would be fine.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode92
> Doc/tutorial/introduction.rst:92: If a variable is not "defined"
(assigned a
> value), trying to use it will
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I really don't like the use of the word 'defined' here.  I'd prefer
something
> > like "A name must be assigned an initial value before it can be
used.  Trying
> to
> > use a name that hasn't been assigned a value will give you an
error:"
> 
> That doesn't sound too well to me.

What about it doesn't sound good?  "defined" just feels *wrong* to me
for
Python.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode137
> Doc/tutorial/introduction.rst:137: double quotes (``"..."``) with the
same
> result.  ``\`` can be used to escape
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I'm not sure "with the same result" is at all clear, here.  I think
it would
> be
> > better to just say "They can be enclosed in either single quotes
(``'...''')
> or
> > double quotes (``"..."``)" and then have the next sentence read
"``\`` can be
> > used to escape a quote character in a string that is surrounded by
that same
> > type of quote character::" which the examples with then make
concrete.
> 
> "with the same result" is supposed to indicate that apart from the
(obvious)
> differences regarding the escaping of \' and \", they behave the same.
 In other
> languages there are differences between the two -- e.g. chars like \n
and \t and
> variable interpolation only work with one kind of quotes.

How about putting that note that other languages do make distinctions
in a footnote?  (Or as a separate sentence.)

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode141
> Doc/tutorial/introduction.rst:141: 'spam eggs'
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I don't think the comments add any value.
> 
> They are useful for people who read only the examples, and to link
part of the
> description with the examples.

OK.  I don't like them personally, but I can deal with that as personal
preference.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode153
> Doc/tutorial/introduction.rst:153: By default, the interpreter
encloses the
> string output in quotes and escapes special characters with
backslashes.  The
> string is enclosed in
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I would narrow this further, and say "At the command prompt, ...",
or "In the
> > interactive interpreter" (shell?) since there really is no
"default". 
> 
> s/By default/In the interactive interpreter/ SGTM.
> 
> > I also
> > would prefer to retain the sense of the 'in the same way'
phrase...perhaps "in
> a
> > way that they could be typed at the input prompt"?
> 
> "In the same way" is not totally accurate, because "s might end up
replaced with
> 's or the other way around.

That's why my suggested replacement uses the word "could" :)

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode180
> Doc/tutorial/introduction.rst:180: triple-quotes: ``"""..."""`` or
> ``'''...'''``.  End of lines are automatically
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > "End of lines are automatically..." This is confusing without the
preceding
> > example of escaping the ends of lines in a single quoted string.
> 
> This is presented in the next example though.
> The idea is that first I introduce """...""" and \ and explain what
they do,
> then I show an example and its output, pointing out what """...""" and
\ did
> there.

Right, and I'm saying that I don't think that exposition works as well.

> >  That section
> > should be retained, IMO. Despite the fact that it is not "best
practice" to
> > write code that way, pedagogically it explains the concepts better.
> 
> The problem with that is that if people see it, it's likely they are
going to
> copy it and use it in their code.
> Even if \ actually works even outside strings, the examples shows one
of the
> very few places where it's ok using it (IMHO).

The text linking the two examples can say that the second one is the
better
way to do it.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode211
> Doc/tutorial/introduction.rst:211: This only works with two literals
though, not
> with variables::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > "arbitrary string expressions" is more correct here than
"variables".
> 
> It's more correct but less clear.  "variables or expressions" might be
OK
> though.

That sounds fine.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode213
> Doc/tutorial/introduction.rst:213: >>> prefix = 'Py'
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > I think you should include an expression example as well, such as
showing that
> > the multiplication example doesn't work with string concatenation. 
(But you
> > should reverse it, 'un' *3 'ium')
> 
> I preferred to show only one example, because each "failing" example
takes 5
> more line, and having two tracebacks one after the other might be
confusing.

You could use the '...' notation and only show the SyntaxError.  That
should
be typographically clear even to a beginner.

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode367
> Doc/tutorial/introduction.rst:367: items of different types, but
usually the
> items all have the same type. ::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > You are losing something here by omitting the example of items of
different
> > type.  How about having both examples, and prefacing the second one
with,
> > "Normally, however, lists elements will all be of the same type"?
> 
> I think it's not necessary, and it's better to keep the tutorial
short.

Well, I still think you are losing something valuable, but I won't block
on it
:)

>
http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode384
> Doc/tutorial/introduction.rst:384: means that the following slice
returns a new
> (shallow) copy of the list::
> On 2013/05/01 18:30:31, r.david.murray wrote:
> > We probably ought to link this to "shallow copy" in the
glossary...and make an
> > entry for it :)
> 
> OK (was there an issue for this?)

I don't think so.


http://bugs.python.org/review/14097/


More information about the docs mailing list