@@ -26,6 +26,7 @@ the footnote reference.
2626
2727Footnotes may appear in the middle of sentences where appropriate.
2828
29+
2930Capitalization
3031==============
3132
@@ -154,6 +155,7 @@ explanation.
154155Please consult the `Diátaxis <https://diataxis.fr/ >`_ guide for more
155156detail.
156157
158+
157159Links
158160=====
159161
@@ -182,6 +184,7 @@ documentation for ``map``. You can suppress the link while keeping the
182184semantic presentation of the function name by adding an exclamation point
183185prefix: ``:func:`!map` ``. See :ref: `roles ` for more details.
184186
187+
185188Affirmative tone
186189================
187190
@@ -207,6 +210,34 @@ language):
207210 achieve the same effect. This assures that files are flushed and file
208211 descriptor resources are released in a timely manner.
209212
213+
214+ Bylines
215+ =======
216+
217+ For new documentation, do not use bylines. They tend to discourage other users
218+ from updating community documentation.
219+
220+ Existing documentation with bylines will not be changed unless the author
221+ decides to do so. This is subject to change in the future.
222+
223+
224+ First-person language
225+ =====================
226+
227+ Avoid first-person language. Our documentation is owned and maintained by a
228+ community. First-person language mistakenly implies a single author.
229+
230+
231+ Pronunciation of dunders
232+ ========================
233+
234+ "Dunder methods" like ``__init__ `` can be awkward in running prose: is it "an
235+ __init__" or "a __init__"? A `quick poll `__ indicates we should use
236+ "an __init__."
237+
238+ __ https://hachyderm.io/@nedbat/112129685322594689
239+
240+
210241Economy of expression
211242=====================
212243
@@ -218,6 +249,7 @@ to understanding and can result in even more ways to misread or misinterpret the
218249text. Long descriptions full of corner cases and caveats can create the
219250impression that a function is more complex or harder to use than it actually is.
220251
252+
221253Security considerations (and other concerns)
222254============================================
223255
@@ -239,6 +271,7 @@ module (for example, OS level pipe buffers filling up and stalling child process
239271these can be documented in a "Common Errors" section and cross-referenced
240272rather than repeated for every affected interface.
241273
274+
242275.. _code-examples :
243276
244277Code examples
@@ -259,6 +292,7 @@ lines and output lines. Besides contributing visual clutter, it makes it
259292difficult for readers to cut-and-paste examples so they can experiment with
260293variations.
261294
295+
262296Code equivalents
263297================
264298
@@ -283,6 +317,7 @@ An example of when not to use a code equivalent is for the :func:`oct` function.
283317The exact steps in converting a number to octal doesn't add value for a user
284318trying to learn what the function does.
285319
320+
286321Audience
287322========
288323
@@ -304,6 +339,7 @@ the documentation wasn't consulted until after the error was made. It is
304339unfortunate, but typically no documentation edit would have saved the user from
305340making false assumptions about the language ("I was surprised by ...").
306341
342+
307343Function signatures
308344===================
309345
0 commit comments