diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index af5c88860..c53d89372 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 `_ 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,29 @@ language): achieve the same effect. This assures that files are flushed and file descriptor resources are released in a timely manner. + +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. + +Existing documentation with bylines will not be changed unless the author +decides to do so. This is subject to change in the future. + + +Pronunciation of dunder names +============================= + +"Dunder names" like ``__init__`` can be awkward in running prose: is it "an +init" or "a dunder init"? Our recommendation is to ignore the underscores and +use the article that is appropriate for the word in the name. A `quick poll`__ +backs this up: "an __init__." + +__ https://hachyderm.io/@nedbat/112129685322594689 + + Economy of expression ===================== @@ -207,6 +233,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 +255,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 +276,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 +301,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 +323,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 ===================