Determine long-term approach for more acronyms
!63129 (merged) originally proposed a lot of new additions to the acronyms list. I hesitated to accept the MR as-is because it brought some long-simmering questions about abbreviation / acronym handling to the forefront. Some data:
- HTML supports the
<abbr>
tag - Markdown does not have a corresponding formatter, and per https://talk.commonmark.org/t/abbreviations-and-acronyms/890, GitHub Flavored Markdown does not introduce one - you have to use the raw
<abbr>
tag - However, https://github.com/markdown-it/markdown-it-abbr introduces an intriguing workaround, but it requires
markdown-it
, which I'm unsure if we use. (I got a few hits for themarkdown-it
string insidegitlab-docs/node_modules
.) - I also found https://github.com/th-h/nanoc-extensions/blob/master/README.md which implies it's time-consuming (how much?) but it could allow us to maintain a centralized
/content/_data/abbreviations.yaml
file with all our accepted abbreviations.
I'd love to identify a solution that lets us bridge the gap between experienced and novice users. I don't know what the right answer is, just that I'm not thrilled with our current handling of acronyms, and would like to fumble toward a better approach. Thus, making an issue for tw-testing so @eread, @marcel.amirault, @cnorris, and I can chat...
(also cc @axil because he'll know what we're using in the backend)
The following discussion from !63129 (merged) should be addressed:
-
@aqualls started a discussion: (+2 comments) @JonstonChan I've picked up this merge request, but I've got some questions I want to talk over with @marcel.amirault and @eread. I've had some questions in the back of my mind about the acronyms test, and they came to the forefront with this merge request.
My main concern: this MR proposes that we add more acronyms to the 'accepted' list. However, I don't know what pages they were taken from, and I'm not clear if, on those pages, we ever actually spell out what the acronym is. How should we proceed here? Should we …
- allow in more acronyms?
- define in the style guide a list of the acronyms we accept?
- cross-check pages to make sure these new acronyms get spelled out?
- some other option I haven't thought of yet?
I'll post a link to this issue in the #docs-tooling channel. I want to make sure we provide @JonstonChan a clear path forward.