Add a note to the style guide about abbreviations#1844
Conversation
resolves python#1824 After the section on specific terms, but before "simple language", add a section that explains that documentation should spell out acronyms, preferring the "<full-spelling> (<acronym>)" format.
Documentation build overview
28 files changed ·
|
|
Hi Stephen, this issue was originally specific to
|
|
Oh, I hadn't even thought to put it in the role usage docs! 🤦 I want to keep some explanation of the rationale. I'll move things as you suggest, and I think the "some assistive technology" note will end up with the roles. Edit done! LMK if it needs more tuning. |
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"
Maybe... I like "Use simple language". It has two virtues:
I could probably be convinced, but we can discuss outside of this PR. 😁 |
|
As I said, that's for another day ;-) I also have to catch up on the Discord discussion. Thanks for the changes, it's what I had in mind. |
|
All commit authors signed the Contributor License Agreement. |
| 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)". |
There was a problem hiding this comment.
There are probably exceptions that we don't want to write out, for example, "HTML" can usually be left as is.
Do we need to mention stuff like this?
There was a problem hiding this comment.
Maybe start the note with, "in general" to allow for exceptions.
There was a problem hiding this comment.
Are we able to describe the primary case for breaking the rule?
For example, what about adding this sentence to the end?
When an acronym is very well known or expanding it could add confusion, as with "HTML" or "IP Address", exercise your judgement.
I wouldn't mind "In general, ..." if the above seems no good.
There was a problem hiding this comment.
I looked at it both ways and added the In general, ... phrasing. My version was too verbose.
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
3 participants
Hat tip to @hugovk for this! Not only the issue (#1824), but also his comments preceding it made this easy to write.
This as a draft because it conflicts with #1828, which is already approved and should ideally merge first.
Once that's done, the exact positioning of this content in the page may change.
Open question: should this be converted to be a subsection of "Use simple language" or "Specific words"?
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
"<full-spelling> (<acronym>)"format.