classification
Title: Tutorial wording implies an understanding of a concept prior to it being introduced
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Lorem Ipsum, docs@python, emilyemorehouse, rhettinger
Priority: normal Keywords:

Created on 2017-08-09 02:37 by Lorem Ipsum, last changed 2017-08-09 19:14 by rhettinger. This issue is now closed.

Messages (4)
msg299962 - (view) Author: Lorem Ipsum (Lorem Ipsum) Date: 2017-08-09 02:37
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:"
msg299966 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-08-09 03:54
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.
msg300018 - (view) Author: Emily Morehouse (emilyemorehouse) * (Python committer) Date: 2017-08-09 15:13
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.
msg300029 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-08-09 19:14
Emily, thanks for the second review.
Lorem, thanks for the suggestion, but we're going to decline.
History
Date User Action Args
2017-08-09 19:14:14rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg300029

stage: resolved
2017-08-09 15:13:14emilyemorehousesetnosy: + emilyemorehouse
messages: + msg300018
2017-08-09 03:54:09rhettingersetnosy: + rhettinger
messages: + msg299966
2017-08-09 02:37:55Lorem Ipsumcreate