Skip to content

Commit 790795c

Browse files
committed
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
1 parent ac03915 commit 790795c

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

documentation/style-guide.rst

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ the footnote reference.
2626

2727
Footnotes may appear in the middle of sentences where appropriate.
2828

29+
2930
Capitalization
3031
==============
3132

@@ -154,6 +155,7 @@ explanation.
154155
Please consult the `Diátaxis <https://diataxis.fr/>`_ guide for more
155156
detail.
156157

158+
157159
Links
158160
=====
159161

@@ -182,6 +184,7 @@ documentation for ``map``. You can suppress the link while keeping the
182184
semantic presentation of the function name by adding an exclamation point
183185
prefix: ``:func:`!map```. See :ref:`roles` for more details.
184186

187+
185188
Affirmative 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+
210241
Economy of expression
211242
=====================
212243

@@ -218,6 +249,7 @@ to understanding and can result in even more ways to misread or misinterpret the
218249
text. Long descriptions full of corner cases and caveats can create the
219250
impression that a function is more complex or harder to use than it actually is.
220251

252+
221253
Security considerations (and other concerns)
222254
============================================
223255

@@ -239,6 +271,7 @@ module (for example, OS level pipe buffers filling up and stalling child process
239271
these can be documented in a "Common Errors" section and cross-referenced
240272
rather than repeated for every affected interface.
241273

274+
242275
.. _code-examples:
243276

244277
Code examples
@@ -259,6 +292,7 @@ lines and output lines. Besides contributing visual clutter, it makes it
259292
difficult for readers to cut-and-paste examples so they can experiment with
260293
variations.
261294

295+
262296
Code equivalents
263297
================
264298

@@ -283,6 +317,7 @@ An example of when not to use a code equivalent is for the :func:`oct` function.
283317
The exact steps in converting a number to octal doesn't add value for a user
284318
trying to learn what the function does.
285319

320+
286321
Audience
287322
========
288323

@@ -304,6 +339,7 @@ the documentation wasn't consulted until after the error was made. It is
304339
unfortunate, but typically no documentation edit would have saved the user from
305340
making false assumptions about the language ("I was surprised by ...").
306341

342+
307343
Function signatures
308344
===================
309345

0 commit comments

Comments
 (0)