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
3 files changed± versions/index.html± documentation/markup/index.html± documentation/style-guide/index.html |
|
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. |
2 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.