[New-bugs-announce] [issue41575] Please use active voice "Return foobar" instead of passive voice "foobar is returned"
Denilson Figueiredo de Sá
report at bugs.python.org
Tue Aug 18 05:35:22 EDT 2020
New submission from Denilson Figueiredo de Sá <denilsonsa at gmail.com>:
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:
> An instance of asyncio.TimerHandle is returned which can be used to cancel the callback.
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.)
Change it to: Return an instance of asyncio.TimerHandle which can be used to cancel the callback.
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
assignee: docs at python
nosy: denilsonsa, docs at python
title: Please use active voice "Return foobar" instead of passive voice "foobar is returned"
versions: Python 3.10, Python 3.8, Python 3.9
Python tracker <report at bugs.python.org>
More information about the New-bugs-announce