From 5e900e337e21d1d5d39d35e3701035a3387058ea Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 25 Jun 2026 20:40:30 -0500 Subject: [PATCH 1/2] Add a note to the style guide about abbreviations resolves #1824 After the section on specific terms, but before "simple language", add a section that explains that documentation should spell out acronyms, preferring the " ()" format. --- documentation/style-guide.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 73618f9ae..125658126 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -116,6 +116,17 @@ Unix 1970s. +Spell out acronyms +================== + +The first time an acronym 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 "JavaScript Object Notation (JSON)". + +Avoid using the ``:abbr:`` role, as it generates HTML which is not accessible to +some forms of assistive technology and mobile users. + + Use simple language =================== From 3b5d5b581512e2d11022517d64c500db1dcec333 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Fri, 26 Jun 2026 12:08:12 -0500 Subject: [PATCH 2/2] Split `:abbr:` vs "acronym howto" docs go The role is documented in with other sphinx roles. In order for the rst to read easily, one line of non-semantic whitespace was added to a list. The acronym usage note is moved to the end of "Use simple language" --- documentation/markup.rst | 6 ++++++ documentation/style-guide.rst | 15 ++++----------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 41bf5b39c..e36aeaa84 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -703,8 +703,14 @@ In the CPython documentation, there are a couple 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. diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 125658126..f19ce300b 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -116,17 +116,6 @@ Unix 1970s. -Spell out acronyms -================== - -The first time an acronym 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 "JavaScript Object Notation (JSON)". - -Avoid using the ``:abbr:`` role, as it generates HTML which is not accessible to -some forms of assistive technology and mobile users. - - Use simple language =================== @@ -136,6 +125,10 @@ 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." +The first time an acronym 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 "JavaScript Object Notation (JSON)". + Charged terminology to avoid ============================