classification
Title: Documentation is too personalized
Type: Stage: patch review
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: fdrake Nosy List: Jim.Jewett, Michael.Felt, cheryl.sabella, docs@python, eric.araujo, ezio.melotti, fdrake, gvanrossum, pitrou, serhiy.storchaka, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2013-06-22 08:28 by serhiy.storchaka, last changed 2020-09-19 19:02 by georg.brandl.

Files
File name Uploaded Description Edit
Imemy.grep serhiy.storchaka, 2013-06-22 08:31
Pull Requests
URL Status Linked Edit
PR 21639 closed Michael.Felt, 2020-07-27 13:06
Messages (13)
msg191636 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-06-22 08:28
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 issue4153).
msg191637 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-06-22 08:31
Here is a filtered results of

   find * -name '*.rst' -exec egrep -n -w -B1 -A1 'I|me|my' '{}' +
msg191685 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2013-06-23 00:37
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
msg192008 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-06-28 18:17
I find some anonymous I references (Guido? 20 years ago?) off-putting when reading the doc as formal reference.
msg192036 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-06-29 13:57
The sockets tutorial deserves a good overhaul :-)
msg295141 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-06-04 20:49
Would it be OK for me to tackle this?
msg295164 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-06-05 04:46
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]
> Would it be OK for me to tackle this?
You could, but I would really like to get you involved in more substantive work that involves thinking about real issues and real code.  IMO, this project isn't worthy of you time and is not on the critical path to your stated goals.   That said, feel free to volunteer for anything that interests you.
msg315557 - (view) Author: Matej Cepl (mcepl) * Date: 2018-04-21 09:07
What about WONTFIX here? I completely agree with rhettinger: this is a waste of time with potential for causing damage.
msg374279 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-25 21:05
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.
msg374326 - (view) Author: Michael Felt (Michael.Felt) * Date: 2020-07-26 15:35
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., is replacing them with a single ' ', or otherwise, a new line ('\n') an error.

iirc - new paragraphs are indicated by two new-lines.
msg374330 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-07-26 16:39
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 https://www.python.org/dev/peps/pep-0012/#general:

   You must adhere to the Emacs convention of adding two spaces at the end of every sentence.

AFAIK in English typography the space after a sentence-ending period is longer than spaces between words. In other European typographies they have the same width.
msg374363 - (view) Author: Michael Felt (Michael.Felt) * Date: 2020-07-27 07:21
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 sentence.

On 26/07/2020 18:39, Serhiy Storchaka wrote:
> Serhiy Storchaka <storchaka+cpython@gmail.com> 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 https://www.python.org/dev/peps/pep-0012/#general:
>
>    You must adhere to the Emacs convention of adding two spaces at the end of every sentence.
>
> AFAIK in English typography the space after a sentence-ending period is longer than spaces between words. In other European typographies they have the same width.

I thought it was where type setters, classically, used the break between
the endings of a sentence - additional 'kerning' could be applied there.

Anyway - final question: does .rst reformat line-lingths, or does it
present everything literally - only adding ``embellishments``. I have
been thinking
it does both - and, yet another convention for sentence endings is to
always start a sentence on a new line (and two new-lines indicate
start of a paragraph.

However, for now - double-spaces will remain - and I hope to remember to
add my own :)

> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue18280>
> _______________________________________
>
msg374443 - (view) Author: Jim Jewett (Jim.Jewett) (Python triager) Date: 2020-07-27 23:34
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.
History
Date User Action Args
2020-09-19 19:02:04georg.brandlsetnosy: - georg.brandl
2020-07-27 23:34:16Jim.Jewettsetnosy: + Jim.Jewett
messages: + msg374443
2020-07-27 13:06:15Michael.Feltsetkeywords: + patch
stage: patch review
pull_requests: + pull_request20780
2020-07-27 07:46:09mceplsetnosy: - mcepl
2020-07-27 07:28:07rhettingersetnosy: - rhettinger
2020-07-27 07:21:01Michael.Feltsetmessages: + msg374363
2020-07-26 16:39:28serhiy.storchakasetmessages: + msg374330
2020-07-26 15:35:01Michael.Feltsetnosy: + Michael.Felt
messages: + msg374326
2020-07-25 21:05:36gvanrossumsetkeywords: + easy
nosy: + gvanrossum
messages: + msg374279

2018-04-21 09:07:12mceplsetnosy: + mcepl
messages: + msg315557
2017-06-05 04:46:07rhettingersetversions: + Python 3.7, - Python 2.7, Python 3.3, Python 3.4
nosy: + fdrake, rhettinger

messages: + msg295164

assignee: docs@python -> fdrake
2017-06-04 20:49:14cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg295141
2014-12-31 16:23:08akuchlingsetnosy: - akuchling
2013-06-29 13:57:49pitrousetnosy: + pitrou
messages: + msg192036
2013-06-28 18:17:13terry.reedysetnosy: + terry.reedy
messages: + msg192008
2013-06-23 00:37:00akuchlingsetmessages: + msg191685
2013-06-22 08:31:07serhiy.storchakasetfiles: + Imemy.grep

messages: + msg191637
2013-06-22 08:28:34serhiy.storchakacreate