Skip to content

Commit

Permalink
move style guide recommendations into devguide
Browse files Browse the repository at this point in the history
These are the remaining items from the (private) Editorial Board style
guide suggestions:
https://docs.google.com/document/d/1rSkUIGFuI5zDMYturyJCo9agYPQ-d53Z3MntSV0rB3E/edit
  • Loading branch information
nedbat committed Aug 21, 2024
1 parent 6ee39a9 commit a650188
Showing 1 changed file with 36 additions and 0 deletions.
36 changes: 36 additions & 0 deletions documentation/style-guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ the footnote reference.

Footnotes may appear in the middle of sentences where appropriate.


Capitalization
==============

Expand Down Expand Up @@ -143,6 +144,7 @@ explanation.
Please consult the `Diátaxis <https://diataxis.fr/>`_ guide for more
detail.


Links
=====

Expand Down Expand Up @@ -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
================

Expand All @@ -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
=====================

Expand All @@ -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)
============================================

Expand All @@ -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
Expand All @@ -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
================

Expand All @@ -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
========

Expand All @@ -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
===================

Expand Down

0 comments on commit a650188

Please sign in to comment.