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.

[kumaraditya303]

cc @python/proofreaders

[pradyunsg]

This is a reasonable suggestion, and a change worth making.

Looking at the asyncio docs, the spots where we're using passive voice are all actually a decent candidate for explicit structured API documentation using Sphinx's :param: and :returns: to describe the arguments and return value.

[bskinn]

decent candidate for explicit structured API documentation using Sphinx's :param: and :returns: to describe the arguments and return value.

I scanned through a handful of pages of the docs, both asyncio and not, and It looks like :param: & co. are only lightly used, if at all.

Is there a general campaign to try to migrate the docs to use these features, @pradyunsg? If not, would it be better to keep to the approach most commonly used elsewhere? It doesn't look like it would give advantages such as, e.g., adding fragment ids or cross-reference targets.

[CAM-Gerlach]

I definitely agree with the premise here—reference documentation such as this should be concise, consistent, clear and easily skimmable.

Beyond just changing these various instances to use direct language and active voice, these functions generally seem like great candidates for adopting a more explicit, structured and consistent form of presenting their information, namely using the appropriate Sphinx constructs, as discussed on Discourse and implemented so far in several other stdlib modules' docs, such as sqlite3 and logging.

However, I suggest we just go ahead and make the initial minimal changes suggested above first before proceeding with those larger ones, to avoid holding this up and going out of scope, and splitting those into atomic units of one per function/method (or at least one per group of adjacent functions/methods), following discussion.

Is there a general campaign to try to migrate the docs to use these features, @pradyunsg? If not, would it be better to keep to the approach most commonly used elsewhere? It doesn't look like it would give advantages such as, e.g., adding fragment ids or cross-reference targets.

There is the beginnings of one, as discussed on Discourse, though it is still early stages and proceeding one module at a time, rather than being a large, formal project at this point, and is also been coupled with other Diataxis-inspired improvements.

[bskinn]

However, I suggest we just go ahead and make the initial minimal changes suggested above first before proceeding with those larger ones

Do we know, is it only the one specific page that needs these edits, or should the entirety of the asyncio docs (or the entire docs suite, even) be checked and corrected?

[bskinn]

A quick search (https://www.google.com/search?q=%22is+returned%22+site%3Adocs.python.org) suggests that a broader campaign may be called for: "About 1,730 results (0.30 seconds)."

[gvanrossum]

Please don't submit a bulk PR. It is likely going to overwhelm reviewers, and unless you are also a subject matter expert, your best intentions will still occasionally change the meaning of certain sentences and make the docs less accurate. I'm speaking from experience here.

Instead, submit small PRs, one at a time, that carefully rewrite one particular section (or several related sections) for legibility.

[bskinn]

Oh, absolutely, @gvanrossum! At most one source file per PR; less than one file per PR in the case of a sufficient number of edits to a single file.

[terryjreedy]

I am a fan of active voice and will review docstring patches to employ such.

I don't like the hugh, ugly, mostly empty purple blobs resulting from the new sphinx markup, such as for sqlite.connect. I think Parameters: should be on a line by itself with the entries below with a small indent. If color is wanted, color the parameter names. I do like the list for more than 2 or 3 parameters. No purple blob. The Returns line seems uselessly redundant, as the return type should be part of the summary sentence. In this instance, I think Return an open Connection to an SQLite database. would be even better than the current summary, which allows for a None return. (Should I make this comment elsewhere? Where?)

[mwichmann]

I'm sure it should be elsewhere :) Agree with you on the purple blob. This is a theme question; I actually switched a project I work on to sphinx_book_theme for this very reason - it puts the header like Parameters on its own line, and then renders the list with a small indent. I'm not proposing CPython switch to that theme as there's tons of history for the current one, just illustrating that it is a theming question we could argue about... somewhere.

[encukou]

somewhere

in https://github.com/python/python-docs-theme/issues

Or look at Lutra: https://pradyunsg-cpython-lutra-testing.readthedocs.io/en/latest/library/sqlite3.html#sqlite3.connect (and discuss in pradyunsg/lutra#31) – Pradyun intends to propose switching to that theme when it's polished.

[CAM-Gerlach]

Oh, absolutely, @gvanrossum! At most one source file per PR; less than one file per PR in the case of a sufficient number of edits to a single file.

+:100:

I don't like the hugh, ugly, mostly empty purple blobs resulting from the new sphinx markup, such as for sqlite.connect.

I'm not a huge fan of it either; I'd also prefer a style like you suggest and sphinx_book_theme uses (which is also similar to what we use in Spyder's and Jupyter's help panes that render docstrings, and general Numpydoc convention). However, adopting a structured syntax in the source allows us to easily change it one place in the theme, rather than having to change it everywhere in the source. Just to be clear, though, that's a separate issue from the initial implementation of this one.

The Returns line seems uselessly redundant, as the return type should be part of the summary sentence.

Sometimes it is mentioned, but given the summary line's primary goal is the very concisely describe the purpose of the function, its not always practical or prudent to use it to explicitly state the exact return type(s), much less do so precisely and with a cross-reference to the type(s) involved, without gumming up what is a supposed to be a "summary" with specific details. An explicit, structured field for the return type makes it easy for authors to specify it as precisely as desired and without having to manually cross-reference the types, and makes it harder to forget to explicitly mention it, while making it easy for readers to quickly find and unambiguously interpret. This also follows what all the major docstring standards (Sphinxdoc, Numpydoc and Googledoc), and other documentation systems (Doxygen, Javadoc, etc) do. And since its structured data, it allows us to present the return type however we prefer.

[kumaraditya303]

All referenced PRs were merged, is there still work to be done or is this completed ?

[bskinn]

@kumaraditya303 There is a great deal more work to be done to complete this. The rest of asyncio-eventloop.rst, beyond the two linked PRs, and then perhaps the remainder of the asyncio docs pages. I've unfortunately had other things intrude on my ability to initiate more of these PRs.

It's a significant undertaking. If it's of continued interest, it might be better to migrate the tracking from this single issue into a GitHub Project or something.

[gvanrossum]

I don't feel that such work is of sufficient importance to keep an issue open. Thank you for your work!