Please use active voice in async docs.

[denilsonsa]

BPO	41575
Nosy	@gvanrossum, @terryjreedy

^{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 = None
created_at = <Date 2020-08-18.09:35:22.015>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Please use active voice in async docs.'
updated_at = <Date 2020-08-21.22:26:07.627>
user = 'https://bugs.python.org/denilsonsa'

bugs.python.org fields:

activity = <Date 2020-08-21.22:26:07.627>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-08-18.09:35:22.015>
creator = 'denilsonsa'
dependencies = []
files = []
hgrepos = []
issue_num = 41575
keywords = []
message_count = 2.0
messages = ['375603', '375771']
nosy_count = 5.0
nosy_names = ['gvanrossum', 'terry.reedy', 'denilsonsa', 'docs@python', 'Yury.Selivanov']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41575'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

Linked PRs

• gh-85747: "Preface" section of asyncio-eventloop.rst: Switch to active voice and suggest other edits #99784
• [3.11] gh-85747: "Preface" section of asyncio-eventloop.rst: Switch to active voice and suggest other edits (GH-99784) #99980
• [3.10] gh-85747: "Preface" section of asyncio-eventloop.rst: Switch to active voice and suggest other edits (GH-99784) #99981
• gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst #100270
• [3.10] gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst (gh-100270) #102005
• [3.11] gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst (GH-100270) #102006

[denilsonsa]

When reading the documentation for call_soon(), call_later(), call_at(), and several other functions, the sentence that describes the return value is in passive voice:
https://docs.python.org/3/library/asyncio-eventloop.html

An instance of asyncio.TimerHandle is returned which can be used to cancel the callback.

The problem:

Most functions in Python documentation describe the return value by "Return foobar", an active voice sentence at the beginning of a paragraph. (e.g. https://docs.python.org/3/library/functions.html ) Thus, for the reader, it's easy to quickly skim the text for the return value. Even easier because the reader is already trained to do so, given other occurrences in the documentation.

However, by hiding "is returned" in the middle of the sentence/paragraph, the reader can't easily find the return value, having to carefully read through all the text. Not only this is slower, but way more difficult if the reader is in a hurry or tired. (That was my case, I missed that sentence even after looking at the documentation several times.)

Solution:

Change it to: Return an instance of asyncio.TimerHandle which can be used to cancel the callback.

Further solution:

Search the documentation for other cases of "is returned" and consider if it is worth rewording as active voice.

Bonus link: https://developers.google.com/tech-writing/one/active-voice

[terryjreedy]

Active voice is strongly recommended for docstrings in PEP-257 and commit messages somewhere in the Developer guide and applies to docs. The doc for the asyncio call_x functions all start with the active voice: 'Schedule', which is the main action of the function. 'is returned' occurs later in the entries and that case is less clear.