From a6501889b8d3f9a3a973db9801a3f82f387c1b46 Mon Sep 17 00:00:00 2001
From: Ned Batchelder <ned@nedbatchelder.com>
Date: Wed, 21 Aug 2024 07:12:52 -0400
Subject: [PATCH] move style guide recommendations into devguide

These are the remaining items from the (private) Editorial Board style
guide suggestions:
https://docs.google.com/document/d/1rSkUIGFuI5zDMYturyJCo9agYPQ-d53Z3MntSV0rB3E/edit
---
 documentation/style-guide.rst | 36 +++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst
index af5c88860f..3fd39c8d1f 100644
--- a/documentation/style-guide.rst
+++ b/documentation/style-guide.rst
@@ -26,6 +26,7 @@ the footnote reference.
 
 Footnotes may appear in the middle of sentences where appropriate.
 
+
 Capitalization
 ==============
 
@@ -143,6 +144,7 @@ explanation.
 Please consult the `Diátaxis <https://diataxis.fr/>`_ guide for more
 detail.
 
+
 Links
 =====
 
@@ -171,6 +173,7 @@ documentation for ``map``.  You can suppress the link while keeping the
 semantic presentation of the function name by adding an exclamation point
 prefix: ``:func:`!map```.  See :ref:`roles` for more details.
 
+
 Affirmative tone
 ================
 
@@ -196,6 +199,34 @@ language):
     achieve the same effect.  This assures that files are flushed and file
     descriptor resources are released in a timely manner.
 
+
+Bylines
+=======
+
+For new documentation, do not use bylines. They tend to discourage other users
+from updating community documentation.
+
+Existing documentation with bylines will not be changed unless the author
+decides to do so. This is subject to change in the future.
+
+
+First-person language
+=====================
+
+Avoid first-person language.  Our documentation is owned and maintained by a
+community.  First-person language mistakenly implies a single author.
+
+
+Pronunciation of dunders
+========================
+
+"Dunder methods" like ``__init__`` can be awkward in running prose: is it "an
+__init__" or "a __init__"?  A `quick poll`__ indicates we should use
+"an __init__."
+
+__ https://hachyderm.io/@nedbat/112129685322594689
+
+
 Economy of expression
 =====================
 
@@ -207,6 +238,7 @@ to understanding and can result in even more ways to misread or misinterpret the
 text.  Long descriptions full of corner cases and caveats can create the
 impression that a function is more complex or harder to use than it actually is.
 
+
 Security considerations (and other concerns)
 ============================================
 
@@ -228,6 +260,7 @@ module (for example, OS level pipe buffers filling up and stalling child process
 these can be documented in a "Common Errors" section and cross-referenced
 rather than repeated for every affected interface.
 
+
 .. _code-examples:
 
 Code examples
@@ -248,6 +281,7 @@ lines and output lines.  Besides contributing visual clutter, it makes it
 difficult for readers to cut-and-paste examples so they can experiment with
 variations.
 
+
 Code equivalents
 ================
 
@@ -272,6 +306,7 @@ An example of when not to use a code equivalent is for the :func:`oct` function.
 The exact steps in converting a number to octal doesn't add value for a user
 trying to learn what the function does.
 
+
 Audience
 ========
 
@@ -293,6 +328,7 @@ the documentation wasn't consulted until after the error was made.  It is
 unfortunate, but typically no documentation edit would have saved the user from
 making false assumptions about the language ("I was surprised by ...").
 
+
 Function signatures
 ===================