[issue31152] Tutorial wording implies an understanding of a concept prior to it being introduced

[Raymond Hettinger]

Raymond Hettinger added the comment:

Emily, thanks for the second review.
Lorem, thanks for the suggestion, but we're going to decline.

--
resolution:  -> rejected
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31152] Tutorial wording implies an understanding of a concept prior to it being introduced

[Emily Morehouse]

Emily Morehouse added the comment:

I concur with Raymond, particularly because paragraph 1 of section 8.5 links to 
the Classes tutorial which covers inheritance. I think the documentation is 
sufficient as is.

--
nosy: +emilyemorehouse

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31152] Tutorial wording implies an understanding of a concept prior to it being introduced

[Raymond Hettinger]

Raymond Hettinger added the comment:

It is okay for the tutorial to occasionally have forward references. 
 Python is a fully object oriented language so references to classes and 
instances will appear in many places.  AFAICT, this particular passage has 
never caused any reported difficulty for any users.  As it reads now, I find it 
to be clear and correct guidance.

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31152] Tutorial wording implies an understanding of a concept prior to it being introduced

[Lorem Ipsum]

New submission from Lorem Ipsum:

Python 3.5.4 Tutorial Section 8.5. User-defined Exceptions Paragraph 2 
(https://docs.python.org/3.5/tutorial/errors.html#user-defined-exceptions) 
states [emphasis mine]:

"When creating a module that can raise several distinct errors, a common 
practice is to create a base class for exceptions defined by that module, and 
SUBCLASS THAT TO create specific exception classes for different error 
conditions:"

The use of 'subclass' as a verb when it has not been used so prior is 
confusing, especially to beginners.  The concept of a class is not formally 
covered until Section 9 and up until this point in the tutorial, 'class' has 
been used as a noun.  When read with 'subclass' as a noun, the sentence is 
nonsensical. It may also be that the comma which precedes 'and' is not proper 
usage. 

Suggested improvement: change "subclass that to create specific classes for..." 
to "then create specific exception subclasses for..."

"When creating a module that can raise several distinct errors, a common 
practice is to create a base class for exceptions defined by that module, and 
then create specific exception subclasses for different error conditions:"

--
assignee: docs@python
components: Documentation
messages: 299962
nosy: Lorem Ipsum, docs@python
priority: normal
severity: normal
status: open
title: Tutorial wording implies an understanding of a concept prior to it being 
introduced
type: enhancement
versions: Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com