Create an interactive glossary of common terms and acronyms

[melchoyce]

Hello!

I'm a new member of 18F and I've been working my way through the Handbook. One feature that I think could be helpful is creating an interactive glossary of common terms and acronyms. Ideally, any time a word in the glossary appears in a page, it's given a style that indicates it's interactive and mousing over or tapping the term opens a popover with the definition:

Dark Popover	Light Popover

You can see the glossary that inspired this issue on the "Make WordPress" blogs:

https://make.wordpress.org/core/

(For reference, the code lives here: https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/plugins/handbook/inc/glossary.php)

Appreciate the consideration!

[geekygirlsarah]

Sounds like a good idea to me!

[mgwalker]

This issue will be closed as inactive on or after November 23. If we should keep this issue open, please add another comment or remove the stale label.

[melchoyce]

What's the best way to move something like this forward?

[mgwalker]

That is a great question. AFAIK, there's not like a product owner for the Handbook, or really even much in the way of governance. It's sort of rag-tag maintained. Which means for new features or new content, someone kind of just has to volunteer to do it.

So... I guess the way forward is to find someone to do it.

[mgwalker]

@melchoyce Do you want to keep this open a little longer to find someone(s) to work on this?

[melchoyce]

Yeah, I'll try to recruit some folks after the holiday. Thanks!

[adunkman]

A few links to help those who might be picking this issue up:

• https://github.com/18F/glossary was used in the past for a few sites, might be good inspiration or something to revive.
• https://github.com/18F/the-glossary powers @charlie define in Slack.

[beechnut]

Building off @adunkman's comment:

• 18F/the-glossary comes with some solid data guarantees, like you'll never see an acronym that doesn't have an expanded term.
• The @charlie define script has logic for fuzzy-matching acronyms and terms, so, for example, you get the same definition for an acronym or term despite variation in spacing and punctuation.

Feel free to ping me for a consultation, I'm an author on both of these.

[mgwalker]

One significant challenge here is just in finding all the terms on a page that are also in the glossary, and doing it in a sensible way (e.g., only the terms that are in the main body of a page) and then turning those into interactive elements in the DOM. That problem is why I didn't volunteer in the first place, because I couldn't see a clear path. I feel like this step would have to be post-build because the pre-build content can be in so many formats (HTML, Markdown, YAML, etc.). The only consistency is post-build, when everything is HTML. (A little bit of good news here is there is already a post-build step that loads every page, parses it into a DOM, manipulates it, and writes it back to disk.)

Alternatively, we could ask Handbook content creators to markup their content. That would be easier from an engineering perspective, but it creates a continuous burden instead of a one-time burden. This one seems like it'd never really take off because people would just forget, or not even know to do it. And any kind of automation to remind people or automatically insert the definitions with this approach would run into the same complexity as above, in which case you might as well just do the above.

[echappen]

I’d definitely find this feature helpful. But I agree with Greg that I don’t see a path that wouldn’t involve either a robust post-build/front end script or a process involving manual tasks for content contributors.

It made me wonder how Wikipedia does their page previews, a feature that I like a lot and use all the time. There, it seems like content editors just add hyperlinks to other Wikipedia pages, and then any Wikipedia link on a page gets displayed as a tooltip.

I could see a basic front end script that scans for any hyperlinks to glossary pages (which we’d need to make and is a whole other discussion), retrieves that page and then dumps a bit of that page’s content into a tooltip. This would make the word search issue moot, but the tradeoff is that content editors would need to add those links to the pages, and do so consistently.

There’s also the issue of tooltip accessibility that any script would complicate.