From 5e900e337e21d1d5d39d35e3701035a3387058ea Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 25 Jun 2026 20:40:30 -0500 Subject: [PATCH 1/4] 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 73618f9aec..125658126e 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/4] 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 41bf5b39c6..e36aeaa84b 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 125658126e..f19ce300b5 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 ============================ From d53162553c35064b8a6b2da607bfd552a0460fea Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Fri, 24 Jul 2026 16:08:49 -0500 Subject: [PATCH 3/4] Add "In general, ..." to soften acronym note Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- documentation/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index fae170aed2..95b089c7a4 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -68,7 +68,7 @@ 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. +In general, 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)". From 0cf86182da8f945618d326a7c9dd28408fe79af9 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sat, 25 Jul 2026 18:07:41 -0500 Subject: [PATCH 4/4] Update documentation/style-guide.rst Co-authored-by: Stan Ulbrych --- documentation/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 95b089c7a4..115cfe6349 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -70,7 +70,7 @@ such as "for example" or "that is." In general, 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)". +For example, write "Basic Multilingual Plane (BMP)". Charged terminology to avoid