Repository navigation
Documentation is too personalized #62480
Description
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 = 'https://github.com/freddrake'
closed_at = None
created_at = <Date 2013-06-22.08:28:34.438>
labels = ['easy', '3.7', 'docs']
title = 'Documentation is too personalized'
updated_at = <Date 2020-09-19.19:02:04.510>
user = 'https://github.com/serhiy-storchaka'bugs.python.org fields:
activity = <Date 2020-09-19.19:02:04.510>
actor = 'georg.brandl'
assignee = 'fdrake'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2013-06-22.08:28:34.438>
creator = 'serhiy.storchaka'
dependencies = []
files = ['30665']
hgrepos = []
issue_num = 18280
keywords = ['patch', 'easy']
message_count = 13.0
messages = ['191636', '191637', '191685', '192008', '192036', '295141', '295164', '315557', '374279', '374326', '374330', '374363', '374443']
nosy_count = 11.0
nosy_names = ['gvanrossum', 'fdrake', 'terry.reedy', 'pitrou', 'ezio.melotti', 'eric.araujo', 'docs@python', 'Jim.Jewett', 'serhiy.storchaka', 'Michael.Felt', 'cheryl.sabella']
pr_nums = ['21639']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue18280'
versions = ['Python 3.7']Linked PRs
- gh-62480: Remove first-person usage for some docs #102295
- gh-62480: De-personalize "Partial mocking" section in
unittest.mockexamples #141321 - gh-62480: De-personalize "Mocking Unbound Methods" section in
unittest.mockexamples #141322 - gh-62480: De-personalize "Coping with mutable arguments" section in
unittest.mockexamples #141323 - [3.14] gh-62480: De-personalize "Mocking Unbound Methods" section in
unittest.mockexamples (GH-141322) #141324 - [3.13] gh-62480: De-personalize "Mocking Unbound Methods" section in
unittest.mockexamples (GH-141322) #141325 - [3.14] gh-62480: De-personalize "Partial mocking" section in
unittest.mockexamples (GH-141321) #141326 - [3.13] gh-62480: De-personalize "Partial mocking" section in
unittest.mockexamples (GH-141321) #141327 - [3.14] gh-62480: De-personalize "Coping with mutable arguments" section in
unittest.mockexamples (GH-141323) #141655 - [3.13] gh-62480: De-personalize "Coping with mutable arguments" section in
unittest.mockexamples (GH-141323) #141656 - gh-62480: Remove first-person language from heapq documentation #144665
- gh-62480: De-personalize docs on using the C API #151784
- [3.15] gh-62480: De-personalize docs on using the C API (GH-151784) #151936
- [3.14] gh-62480: De-personalize docs on using the C API (GH-151784) #151937
- [3.13] gh-62480: De-personalize docs on using the C API (GH-151784) #151938
Metadata
Metadata
Assignees
Projects
- Status
Activity
serhiy-storchaka commentedon Jun 22, 2013
Some documentation files contain a number of I/my/me. Looks like they grew from personal modules and personal articles. Perhaps the official documentation needs more depersonalized style. Here is full list of such files:
Doc/c-api/exceptions.rst
Doc/c-api/long.rst
Doc/distutils/builtdist.rst
Doc/extending/extending.rst
Doc/extending/windows.rst
Doc/howto/argparse.rst
Doc/howto/curses.rst
Doc/howto/functional.rst
Doc/howto/regex.rst
Doc/howto/sockets.rst
Doc/howto/urllib2.rst
Doc/install/index.rst
Doc/library/audioop.rst
Doc/library/ctypes.rst
Doc/library/doctest.rst
Doc/library/heapq.rst
Doc/library/numbers.rst
Doc/library/ossaudiodev.rst
Doc/library/tk.rst
Doc/library/unittest.mock-examples.rst
Doc/library/unittest.mock.rst
Doc/reference/introduction.rst
Doc/tutorial/classes.rst
The list doesn't include FAQs where it may be appropriate and whatsnew files.
Andrew Kuchling recently has fixed Doc/howto/unicode.rst for this issue (as part of bpo-4153).
serhiy-storchaka commentedon Jun 22, 2013
Here is a filtered results of
find * -name '*.rst' -exec egrep -n -w -B1 -A1 'I|me|my' '{}' +
akuchling commentedon Jun 23, 2013
I've looked through the matches. "I/O" and the -I command-line switch are false positives. Many references in the FAQ ("How do I do X?"), but those don't need to be fixed.
I think personalized references are most problematic when they're expressing uncertainty ("I don't know if we implement all of the spec") or opinions. Sentences like "When I run this command under Linux, I see..." could be rewritten as "When *you* run this command...", but they don't seem worth fixing to me.
Files with personalized text are:
c-api/exceptions.rst
c-api/long.rst
distutils/builtdist.rst
extending/extending.rst
install/index.rst
library/audioop.rst
library/ctypes.rst
library/doctest.rst
library/heapq.rst
library/imaplib.rst
library/numbers.rst
library/ossaudiodev.rst
library/unittest.mock-examples.rst
library/unittest.mock.rst
reference/introduction.rst
tutorial/classes.rst
terryjreedy commentedon Jun 28, 2013
I find some anonymous I references (Guido? 20 years ago?) off-putting when reading the doc as formal reference.
pitrou commentedon Jun 29, 2013
The sockets tutorial deserves a good overhaul :-)
csabella commentedon Jun 4, 2017
Would it be OK for me to tackle this?
rhettinger commentedon Jun 5, 2017
Fred, do you want to opine on this?
In some cases, like heapq.py, the personal touch is an essential and beautiful part of the presentation and is a cherished part of Python. In other cases, it seems unnecessary or a little off-putting, so perhaps a few changes are warranted.
Personally, I've grown to really dislike the incessant stream of proposals to make broad sweeping trivial changes across the code or documentation to fix made-up problems (ones not reported or cared about by actual users). In particular, I worry about sending some new dev on a mission to rewrite documentation that was written by domain experts (Alex Martelli reported that copy-editors "wreaked havoc" on one of his books just prior to publication by subtly changing the meaning or correctness of his prose while applying grammar rules and minor style edits -- I wish to avoid the same for us).
Also, I place high value on text written by Guido and think we lose something every time someone wants to rewrite it to fit their personal tastes and views of the language. The tastes and views of module authors are more important are easily lost in style edits (especially those that change point of view, mood, or theme of presentation).
Another thought is that there should be different general rules for different sections. The standard library docs tend to be more formal. The language reference tends to be even more formal ("for language lawyers"). The tutorial tends to be personable. The how-to guides are often have a personal touch and are the only places where we attribute authorship back individuals (actual by-lines at the top of the file).
[Cheryl Sabella]
mcepl commentedon Apr 21, 2018
What about WONTFIX here? I completely agree with rhettinger: this is a waste of time with potential for causing damage.
gvanrossum commentedon Jul 25, 2020
Marking this as "easy". People are welcome to submit PRs that fix the wording in one or a small number of modules called out in Serhiy's list.
23 remaining items
[3.14] gh-62480: De-personalize "Mocking Unbound Methods" section in …
[3.13] gh-62480: De-personalize "Mocking Unbound Methods" section in …
[3.13] gh-62480: De-personalize "Partial mocking" section in `unittes…
[3.14] gh-62480: De-personalize "Partial mocking" section in `unittes…
gh-62480: De-personalize "Coping with mutable arguments" section in `…
pythongh-62480: De-personalize "Coping with mutable arguments" sectio…
pythongh-62480: De-personalize "Coping with mutable arguments" sectio…
pythongh-62480: De-personalize "Mocking Unbound Methods" section in `…
pythongh-62480: De-personalize "Partial mocking" section in `unittest…
pythongh-62480: De-personalize "Coping with mutable arguments" sectio…
gh-62480: De-personalize docs on using the C API (#151784)
[3.13] gh-62480: De-personalize docs on using the C API (GH-151784) (#…
[3.14] gh-62480: De-personalize docs on using the C API (GH-151784)
[3.15] gh-62480: De-personalize docs on using the C API (GH-151784) (#…
pythongh-62480: De-personalize docs on using the C API (python#151784)