Skip to content

Add a note to the style guide about abbreviations #1844

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
StanFromIreland merged 7 commits into from
Jul 28, 2026
Merged

Add a note to the style guide about abbreviations #1844

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5e900e3
Add a note to the style guide about abbreviations
sirosen Jun 26, 2026
3b5d5b5
Split `:abbr:` vs "acronym howto" docs go
sirosen Jun 26, 2026
7555c40
Merge branch 'main' into add-abbreviations-to-style-guide
sirosen Jul 24, 2026
d531625
Add "In general, ..." to soften acronym note
sirosen Jul 24, 2026
0cf8618
Update documentation/style-guide.rst
sirosen Jul 25, 2026
d0cdf9e
Add a small note on acronyms not to expand
sirosen Jul 28, 2026
7ac2c8f
Apply fixes per review
sirosen Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions documentation/markup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 5 additions & 0 deletions documentation/style-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,11 @@ 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 is used on a page, spell it out.

@JelleZijlstra JelleZijlstra Jul 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ironically nothing in the devguide defines the "HTML" abbreviation which you use in the other part of this PR. And I think that's a good thing: in computing there are some terms that are more widely understood as abbreviations than as the full form, and adding the full form is more likely to distract than to help readers. HTML is one of those terms. Other examples off the top of my head are UTF-8, PNG, SVG, SQL.

@sirosen sirosen Jul 26, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, sometimes an acronym becomes a term or word in its own right.
The guidance should be read as flexible in this respect.

We added the "In general" to try to succinctly cover this. Do you feel it needs more explanation? We can try another arrangement if the current text looks too strong.

@JelleZijlstra JelleZijlstra Jul 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current text will likely lead people to comment that you need to say "Hyper-Text Markup Language". I'd suggest wording like "Commonly understood acronyms such as HTML or UTF-8 do not need to be expanded."

@sirosen sirosen Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried a few different "spellings" of the idea, and ended up with almost exactly this suggested text.

(Sorry, I broke the typical rules and did an amend, as I forgot to put Jelle in as a co-author at first!)

@StanFromIreland StanFromIreland Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as I forgot to put Jelle in as a co-author at first!)

In that case, in the future please comment for whoever is merging to add it in (we squash anyway), to avoid amends.

@hugovk hugovk Jul 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or add an empty commit with the co-author, or don't worry about it :)

@sirosen sirosen Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll use an empty commit if it comes up again! That way, it's automatically included in the squash and nobody has to do anything extra.

I strive for perfection, including in my citations. Clearly I need to take the no-force-pushes rule into account more strongly! 😅

@StanFromIreland StanFromIreland Jul 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we also add "abbreviation" here please.

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
============================
Expand Down
Loading