Add further recommendations to the style guide #1377

nedbat · 2024-08-21T11:13:35Z

These are the remaining items from the (private) Editorial Board style guide suggestions:
https://docs.google.com/document/d/1rSkUIGFuI5zDMYturyJCo9agYPQ-d53Z3MntSV0rB3E/edit

📚 Documentation preview 📚: https://cpython-devguide--1377.org.readthedocs.build/

These are the remaining items from the (private) Editorial Board style guide suggestions: https://docs.google.com/document/d/1rSkUIGFuI5zDMYturyJCo9agYPQ-d53Z3MntSV0rB3E/edit

nedbat · 2024-08-21T11:31:33Z

The changelog entry: python/editorial-board#14

documentation/style-guide.rst

Mariatta

Thank you!

AA-Turner

I wonder if we should both make the Google document(s) public and link them here, both in the spirit of working in the open and to preserve project history?

Otherwise, have left a few notes.

A

AA-Turner · 2024-08-21T16:10:10Z

documentation/style-guide.rst

+Author attribution
+==================
+
+For new documentation, do not use a byline (naming the author of the document).
+Explicit attribution tends to discourage other users from updating community
+documentation.


I'd be interested to see background on this, if possible. I've personally never felt deterred by a byline, and it is a nice way to credit someone who's written a major guide or document. However, perhaps there is a more quantitative study that we could reference if introducing this guidance?

I do feel uneasy about changing docs that are attributed to a specific author. It feels like I'm putting words in their mouth that they may not agree with.

I think it depends on the type of document and the type of change. For example, updating module docs is easier than updating a howto, since in the howto the original author might have had a more specific vision and goals.

On the other hand, having a byline is also useful to get in touch with the original author and ask for advice and reviews before making major changes (this could technically be replaced by git blame and CODEOWNERS).

it is a nice way to credit someone who's written a major guide or document

How do we credit someone who has written a major code changes? I don't think we add their name to the top of module name, so why would this be any different? This is an open source documentation not a blog.

having a byline is also useful to get in touch with the original author and ask for advice and reviews before making major changes (this could technically be replaced by git blame and CODEOWNERS)

As you said, this can be done by git blame and codeowners. However I would like for us to rethink the notion that the original author is the only one capable of reviewing/giving advice. Their advice may be sought, but should not be the only advice that matters, and should not be the only advice we rely on. Other contributors' review and advice should be taken into consideration equally.

My experience in CPython is that personal ownership of areas has sometimes given rise to conflicts when other contributors wanted to meaningfully participate (without always bowing to the original author's preferences). So I'm in favor of this guideline.

I agree with @pitrou.

I do feel uneasy about changing docs that are attributed to a specific author

@JelleZijlstra I am supportive of this for existing documentation. However, this PR is concerning new documentation 😄

I'd be interested to see background on this, if possible. I've personally never felt deterred by a byline, and it is a nice way to credit someone who's written a major guide or document. However, perhaps there is a more quantitative study that we could reference if introducing this guidance?

@AA-Turner The byline style recommendation is related to new documentation. We have seen that bylines in certain areas of the documentation has caused conflicts where an individual acts as owner of the community resource. We see similar behavior when we look at academic publishing: https://pubmed.ncbi.nlm.nih.gov/31161378/

My general feeling is that reference documentation should not have bylines. As others have mentioned git blame or git log can offer recognition. If someone creates a new "How to", I think it would be reasonable to recognize in release notes/what's new as we do code contributions.

I am supportive of this for existing documentation. However, this PR is concerning new documentation

True. We could also consider removing bylines from existing documentation, or replacing them with something more indefinite like "Originally written by Jelle Zijlstra; maintained by the community". However, that's out of scope for this change.

I like the suggestion @JelleZijlstra for future wording:

"Originally written by Jelle Zijlstra; maintained by the community"

AA-Turner · 2024-08-21T16:16:36Z

documentation/style-guide.rst

+First-person language
+=====================
+
+Avoid first-person language.  Our documentation is owned and maintained by a
+community.  First-person language mistakenly implies a single author.


Would it be nicer to phrase this positively, saying something like:

Suggested change

First-person language

=====================

Avoid first-person language. Our documentation is owned and maintained by a

community. First-person language mistakenly implies a single author.

Grammatical person

==================

We try to maintain a consistent tone of voice across our documentation.

As part of this, prefer using the third-person when writing reference text and either the second or third person when writing tutorials or guides, which are naturally more 'interactive'.

This removes the negative language from the text, and additionally provides better guide rails for authors of different types of text.

Should a note be added about existing documents that use the first-person?
Adding a few examples would be useful too.
Is the first-person plural allowed? I've seen it used (and used it myself) in tutorials and howtos.

I like the original language here better than @AA-Turner's suggestion; it is more concise and clear.

My concrete suggestion was a very quick draft -- the point was more about using constructive language and adding more guidance. Just to clarify that the suggestion is more an opening offer than final wording!

Style guides often tell you what to avoid. A quick example:

https://developers.google.com/style/inclusive-documentation

I like the idea of providing examples of good and bad usage. Also, first-person plural can be useful: "If we change the method like this, ..."

I'll work on a re-wording tomorrow.

I've done some more reading and thinking, and I'd like to remove this from this pull request and have more discussion before making a recommendation.

BTW, here is a pull request that removes some first-person language: https://github.com/python/cpython/pull/107449/files, with discussion.

documentation/style-guide.rst

willingc · 2024-08-22T18:37:10Z

documentation/style-guide.rst

+Author attribution
+==================
+
+For new documentation, do not use a byline (naming the author of the document).
+Explicit attribution tends to discourage other users from updating community
+documentation.


I agree with @pitrou.

willingc · 2024-08-22T18:39:25Z

documentation/style-guide.rst

+Author attribution
+==================
+
+For new documentation, do not use a byline (naming the author of the document).
+Explicit attribution tends to discourage other users from updating community
+documentation.


I do feel uneasy about changing docs that are attributed to a specific author

@JelleZijlstra I am supportive of this for existing documentation. However, this PR is concerning new documentation 😄

Once python/devguide#1377 merges.

move style guide recommendations into devguide

a650188

These are the remaining items from the (private) Editorial Board style guide suggestions: https://docs.google.com/document/d/1rSkUIGFuI5zDMYturyJCo9agYPQ-d53Z3MntSV0rB3E/edit

nedbat requested review from willingc, jablonskidev and Mariatta August 21, 2024 11:13

nedbat mentioned this pull request Aug 21, 2024

Add Editorial Board Meeting Notes from Feb-Aug '24 python/editorial-board#12

Merged

nedbat mentioned this pull request Aug 21, 2024

add more style recommendations to the changelog python/editorial-board#14

Merged

pitrou reviewed Aug 21, 2024

View reviewed changes

documentation/style-guide.rst Outdated Show resolved Hide resolved

clarify what a byline is

ab93e2d

Mariatta approved these changes Aug 21, 2024

View reviewed changes

AA-Turner reviewed Aug 21, 2024

View reviewed changes

AA-Turner changed the title ~~move style guide recommendations into devguide~~ Add further recommendations to the style guide Aug 21, 2024

expand on the style recommendation for dunder pronunciation

7e3e45d

nedbat force-pushed the nedbat/style-guide-updates branch from 1a7ded5 to 7e3e45d Compare August 21, 2024 23:32

remove 'avoid first person' for now

1f4642f

willingc approved these changes Aug 22, 2024

View reviewed changes

nedbat merged commit b16430b into python:main Aug 28, 2024
4 checks passed

nedbat deleted the nedbat/style-guide-updates branch August 28, 2024 11:05

nedbat added a commit to python/editorial-board that referenced this pull request Sep 25, 2024

add more style recommendations to the changelog (#14)

c0470c8

Once python/devguide#1377 merges.

Uh oh!

Add further recommendations to the style guide #1377

Add further recommendations to the style guide #1377

Uh oh!

Conversation

nedbat commented Aug 21, 2024 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nedbat commented Aug 21, 2024

Uh oh!

Uh oh!

Mariatta left a comment

Choose a reason for hiding this comment

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pitrou Aug 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nedbat commented Aug 21, 2024 •

edited by github-actions bot

Loading

pitrou Aug 22, 2024 •

edited

Loading