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. |
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
|
|
||
| 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)". |
There was a problem hiding this comment.
| For example, write "JavaScript Object Notation (JSON)". | |
| For example, write "Basic Multilingual Plane (BMP)". |
I think 'JSON' is common enough that we don't always need to provide the full term. I suggest we use BMP instead (the abbreviation that led to the issue).
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.