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

[LoremIpsum]

BPO	31152
Nosy	@rhettinger, @emilyemorehouse

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-08-09.19:14:14.846>
created_at = <Date 2017-08-09.02:37:55.342>
labels = ['type-feature', 'docs']
title = 'Tutorial wording implies an understanding of a concept prior to it being introduced'
updated_at = <Date 2017-08-09.19:14:14.845>
user = 'https://bugs.python.org/LoremIpsum'

bugs.python.org fields:

activity = <Date 2017-08-09.19:14:14.845>
actor = 'rhettinger'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-08-09.19:14:14.846>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2017-08-09.02:37:55.342>
creator = 'Lorem Ipsum'
dependencies = []
files = []
hgrepos = []
issue_num = 31152
keywords = []
message_count = 4.0
messages = ['299962', '299966', '300018', '300029']
nosy_count = 4.0
nosy_names = ['rhettinger', 'docs@python', 'emilyemorehouse', 'Lorem Ipsum']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue31152'
versions = ['Python 3.5']

[LoremIpsum]

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:"

[rhettinger]

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.

[emilyemorehouse]

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.

[rhettinger]

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