diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 73618f9ae..74d32d1b7 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -58,6 +58,35 @@ of these entities are not assigned any special markup, but the preferred spellings are given in :ref:`specific words` to aid authors in maintaining the consistency of presentation in the Python documentation. + +Use simple language +=================== + +Avoid esoteric phrasing where possible. Our audience is world-wide and may not +be native English speakers. + +Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, +such as "for example" or "that is." + + +Charged terminology to avoid +============================ + +Avoid terminology that may be considered insensitive or exclusionary. + +.. list-table:: + :header-rows: 1 + + * - Avoid + - Instead + * - whitelist + - allowlist + * - blacklist + - blocklist, denylist + * - master/slave + - main, parent/child, server/client, primary/secondary + + .. _specific words: Specific words @@ -116,32 +145,25 @@ Unix 1970s. -Use simple language -=================== +Type names +========== -Avoid esoteric phrasing where possible. Our audience is world-wide and may not -be native English speakers. - -Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, -such as "for example" or "that is." +When writing the names of types in prose, write the name of the type +exactly as it appears in source, styled as a class reference or an unlinked +class. For example, refer to dict as ``:class:`dict`‌`` or ``:class:`!dict`‌``. +Links should be used according to the :ref:`guidance on links `. -Charged terminology to avoid -============================ +Some type names are commonly understood ideas or nouns outside of Python. +For example, "tuples" are a general programming concept, as distinct from the +``tuple`` type. When referring to general ideas, do not style the relevant word +as a type. -Avoid terminology that may be considered insensitive or exclusionary. - -.. list-table:: - :header-rows: 1 - - * - Avoid - - Instead - * - whitelist - - allowlist - * - blacklist - - blocklist, denylist - * - master/slave - - main, parent/child, server/client, primary/secondary +Many types have descriptive names which do not exactly match their type +name. For example, "context variables" describes ``contextvars.ContextVar``, +and "partial function" may be used to describe an application of +``functools.partial``. Use these names only when they serve to clarify the text +better than the type name itself would, and put them in lowercase. .. index:: diataxis