One of my favorite things about being on the product team at Rest of World is working on experimental story formats that don’t quite match our regular articles: Ambaniverse, gift guides, RoW 100, among others. Often they can involve big changes that readers notice immediately when they’re on the page, but they can also include subtle shifts, like changing the header and dividers between sections or adding CSS transitions to images so they mimic collectible football stickers being placed on a page. 

In April 2022, the Rest of World team worked on an in-depth series, Blackouts, about internet shutdowns around the world. The product team experimented with a glossary section. The goal was to present a list of terms with explanatory text that could quickly help readers understand unfamiliar words and phrases as they read through the story.  

These treatments require us to add custom Javascript and CSS that adapt regular articles to new formats. The changes can range from color updates that repurpose our dark mode to generating a table of contents and breaking an article into sections that track a user’s progress as they scroll.

For the glossary module, we used Javascript to insert a glossary that pulled terms and definitions from a JSON file that we created using information from a document that editors updated. This was mostly to prevent the glossary from showing up in Apple News, which renders whatever content is in the CMS (custom code isn’t applied in Apple News, but we sometimes modify how specific articles are displayed in Apple News before publishing it there). 

Two months later, the editorial team requested this feature again for a story on Axie Inifinity. We reused what was done in the glossary block but with additional improvements and changes. 

The glossary was a useful way of explaining story terms to readers, and, subsequently, editors wanted to continue using the feature. Therefore, it made sense to create a new block, the Glossary Block, within WordPress. Editors could use it at their discretion, and the engineering team would not need to manually code changes. Thus, a ticket was created alongside product specifications detailing the acceptance criteria.

Creating a permanent Glossary Block involved asking questions about how the user interface within WordPress would function. We also factored in how the editorial team might use the block within CMS, such as deleting terms easily, changing the card order, and moving the glossary within the article. Whenever we re-factor a one-off feature to a permanent one, we try to anticipate future usage.

An important consideration is sanitizing the text editors enter and accounting for user error. Should we limit the amount of text used for the definition or take steps to prevent rich-text from being pasted in? We added a scrollbar to the front end, in case the text definitions overflowed the card. Should users be able to link out different parts of the card? Initially, this was unsupported, but we later added an extended toolbar to let users highlight, italicize, and link text in the description.

On the front-end, the look of the Glossary Block remained mostly the same; we revisited the HTML tags we used when rendering the blocks. In the initial version, we used generic paragraph text (<p>) and heading tags (<h3>) for the definitions and terms; however, that wasn’t optimal for screen readers in giving context to the Glossary Block. The HTML spec already had tags specific to what we were doing. We wrapped the entire glossary in a description list tag (<dl>) and used <dt> and <dl> to tag the glossary term and definition, respectively. 

The first article using the Glossary Block was published in September 2022. We updated past articles, Blackouts and Axie Infinity, that relied on custom code to use the block.

However, since enabling the Glossary Block in our production site, we have caught a few bugs, such as scroll bars appearing on large screens or our newsletter appearing underneath the glossary. There were also scenarios we did not consider, like whether to hide it in Apple News or not (we eventually did). 

In the background, as with other components on our site, the product team quietly puts up fixes, as the glossary continues to be used in articles and iterated upon. The more the Glossary Block gets used, the more the product team is able to identify and patch bugs and experiment with other potential features and improvements, like adding images to the glossary.