[issue18280] Documentation is too personalized

Change by Georg Brandl : -- nosy: -georg.brandl ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue18280] Documentation is too personalized

Jim Jewett added the comment: I won't speak of nroff or troff in particular, but many programs had trouble distinguishing the end of a sentence from an honorific abbreviation, such as Mr. Spock or Dr. Seuss. -- nosy: +Jim.Jewett ___ Python

[issue18280] Documentation is too personalized

Change by Michael Felt : -- keywords: +patch pull_requests: +20780 stage: -> patch review pull_request: https://github.com/python/cpython/pull/21639 ___ Python tracker ___

[issue18280] Documentation is too personalized

Change by Matej Cepl : -- nosy: -mcepl ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue18280] Documentation is too personalized

Change by Raymond Hettinger : -- nosy: -rhettinger ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue18280] Documentation is too personalized

Michael Felt added the comment: Thanks. afaik, double spacing is a 'feature' a programmer added to a text processing language - of the WYSIWUG kind, because program's such as troff/nroff didn't need them. They, rather it, understood that a period followed by a space indicated the end of a

[issue18280] Documentation is too personalized

Serhiy Storchaka added the comment: I think they are not required, but recommended. >From https://www.python.org/dev/peps/pep-0008/#comments: You should use two spaces after a sentence-ending period in multi- sentence comments, except after the final sentence. >From

[issue18280] Documentation is too personalized

Michael Felt added the comment: I am taking a look at these, and I am sure there is a PEP I am unaware of - atm - so, a quick question. Is the double space at the end of a sentence 'required' by the rst processing, or is this also a 'personal' writing style in some of the documents (i.e.,

[issue18280] Documentation is too personalized

Guido van Rossum added the comment: 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. -- keywords: +easy nosy: +gvanrossum ___ Python tracker

[issue18280] Documentation is too personalized

Matej Cepl added the comment: What about WONTFIX here? I completely agree with rhettinger: this is a waste of time with potential for causing damage. -- nosy: +mcepl ___ Python tracker

[issue18280] Documentation is too personalized

Raymond Hettinger added the comment: 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

[issue18280] Documentation is too personalized

Cheryl Sabella added the comment: Would it be OK for me to tackle this? -- nosy: +csabella ___ Python tracker ___

[issue18280] Documentation is too personalized

Changes by A.M. Kuchling a...@amk.ca: -- nosy: -akuchling ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue18280 ___ ___ Python-bugs-list mailing

[issue18280] Documentation is too personalized

Antoine Pitrou added the comment: The sockets tutorial deserves a good overhaul :-) -- nosy: +pitrou ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue18280 ___

[issue18280] Documentation is too personalized

Terry J. Reedy added the comment: I find some anonymous I references (Guido? 20 years ago?) off-putting when reading the doc as formal reference. -- nosy: +terry.reedy ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue18280

[issue18280] Documentation is too personalized

New submission from Serhiy Storchaka: 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

[issue18280] Documentation is too personalized

Serhiy Storchaka added the comment: Here is a filtered results of find * -name '*.rst' -exec egrep -n -w -B1 -A1 'I|me|my' '{}' + -- Added file: http://bugs.python.org/file30665/Imemy.grep ___ Python tracker rep...@bugs.python.org

[issue18280] Documentation is too personalized

A.M. Kuchling added the comment: 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