[New-bugs-announce] [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 at python
components: Documentation
messages: 299962
nosy: Lorem Ipsum, docs at 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 <report at bugs.python.org>
<http://bugs.python.org/issue31152>
_______________________________________