Add a note to the style guide about abbreviations

developer-workflow/development-cycle.rst

@@ -146,7 +146,7 @@ Stages
 
 Based on what stage the :ref:`in-development <indevbranch>` version of Python
 is in, the responsibilities of a core team member change in regards to commits
-to the :abbr:`VCS (version control system)`.
+to the VCS (version control system).
 
 
 Pre-alpha

developer-workflow/stdlib.rst

@@ -1,3 +1,3 @@
 .. _stdlib:
 .. _stdlibchanges:
 
@@ -109,7 +109,7 @@
 stdlib and that which is released outside the stdlib (typically done to provide
 the module to older versions of Python). It also removes the burden of forcing
 the core team to have to redirect bug reports or changes to an external issue
-tracker and :abbr:`VCS (version control system)`.
+tracker and VCS (version control system).
 
 Someone involved with the development of the
 module must promise to help maintain the module in the stdlib for two years.
@@ -124,7 +124,7 @@
 
 If the module you want to propose adding to the stdlib meets the requirements,
 you may propose its inclusion
-by following the :abbr:`PEP (Python Enhancement Proposal)` process.
+by following the PEP (Python Enhancement Proposal) process.
 See :pep:`1` for details,
 and the :pep:`PEP index <0>` for previously accepted PEPs
 that have proposed a module for inclusion.

development-tools/clinic/index.rst

@@ -1,3 +1,3 @@
 .. highlight:: c
 
 .. _clinic:
@@ -148,7 +148,7 @@
 Command-line interface
 ----------------------
 
-The Argument Clinic :abbr:`CLI (Command-Line Interface)` is typically used to
+The Argument Clinic CLI (Command-Line Interface) is typically used to
 process a single source file, like this:
 
 .. code-block:: shell-session

documentation/markup.rst

@@ -699,12 +699,18 @@ As :ref:`previously mentioned <inline-markup>`, Sphinx uses
 interpreted text roles of the form ``:rolename:`content```
 to insert semantic markup in documents.
 
-In the CPython documentation, there are a couple common cases
+In the CPython documentation, there are a few common cases
 where simpler markup should be used:
 
 * ``*arg*`` (rendered as *arg*) for function and method arguments.
+
 * ````True````/````False````/````None```` for ``True``/``False``/``None``.
 
+* ``Full Spelling (abbreviation)`` for abbreviations and acronyms.
+
+  The ``:abbr:`` role generates HTML which is not accessible to some forms of
+  assistive technology and mobile users.
+
 In addition, the CPython documentation defines a few custom roles:
 
 * ``:gh:`ID```: link to a GitHub issue.

documentation/style-guide.rst

@@ -68,6 +68,12 @@ 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."
 
+In general, the first time an acronym or abbreviation is used on a page, spell
+it out.
+Prefer to write out the full term and follow it with the acronym in parentheses.
+For example, write "Basic Multilingual Plane (BMP)".
+Commonly understood acronyms, such as "HTML" and "UTF-8", should not be expanded.
+
 
 Charged terminology to avoid
 ============================

getting-started/pull-request-lifecycle.rst

@@ -710,11 +710,10 @@ do not take it personally! Your work is still appreciated regardless of whether
 your pull request is merged. Balancing what *does* and *does not* go into
 Python is tricky and we simply cannot accept everyone's contributions.
 
-But if your pull request is merged it will then go into Python's
-:abbr:`VCS (version control system)` to be released
-with the next feature release of Python. It may also be backported to older
-versions of Python as a bugfix if the core team member doing the merge believes
-it is warranted.
+But if your pull request is merged it will then go into Python's VCS (version
+control system) to be released with the next feature release of Python.
+It may also be backported to older versions of Python as a bugfix if the core
+team member doing the merge believes it is warranted.
 
 
 Crediting

getting-started/setup-building.rst

@@ -1107,8 +1107,7 @@ every rule.
      See also :ref:`building-doc`.
 
 ``Grammar``
-     Contains the :abbr:`PEG (Parser Expression Grammar)` grammar file for
-     Python.
+     Contains the PEG (Parser Expression Grammar) grammar file for Python.
 
 ``Include``
      Contains all interpreter-wide header files.

testing/coverage.rst

@@ -7,7 +7,7 @@ Increase test coverage
 .. include:: /include/activate-tab.rst
 
 Python development follows a practice that all semantic changes and additions
-to the language and :abbr:`stdlib (standard library)` are accompanied by
+to the language and stdlib (standard library) are accompanied by
 appropriate unit tests. Unfortunately Python was in existence for a long time
 before the practice came into effect. This has left chunks of the stdlib
 untested which is not a desirable situation to be in.