Identify and annotate jargon in documents


Jargon is a special language that is used to communicate complex ideas between people concisely. Unfortunately, jargon is inherently exclusionary. People who don't know the jargon within a particular domain are often prevented from accessing the more important and interesting ideas that are gated behind jargon. By making jargon more accessible, we make information available to a much broader group of people than it otherwise would have been.

Jargon(e) is a browser extension that aims to improve information access on the internet. By making knowledge-sharing easier, Jargon(e) helps to make sure that no mind is left behind. Jargon(e) accomplishes this by pulling information from shared repositories of jargon information on the internet and embedding that information directly into web pages.

There are numerous challenges in making Jargon(e) useful:

  1. Jargon definitions should be relevant for the context wherein they are displayed.
  2. Jargon components should be interactive but still preserve existing document structure and behavior.
  3. People need to be able to share their knowledge about jargon in the domains that they know with others.
  4. Jargon(e) needs to be able to process large web pages without slowing users down.

Related Work

Before taking on this project, I wanted to understand my target audience and read about existing work that closely connects to this project. Although the experience of being excluded confronted by unfamiliar jargon is not unique to any group of people, I wanted to specifically address people with brain fog with this work.

In an academic poster from 2009 titled "End-user moderation of cognitive accessibility in online communities: case study of brain fog in the lyme community" by Kit Kuksenok and Jennifer Mankoff, the authors presented their findings that individuals with brain fog can "have difficulty remembering the start of a long passage by the end."

In a YouTube video titled "What "Brain Fog" Feels Like" someone who experiences brain fog shared how they are impacted by the condition. According to them, they sometimes have difficulty recalling specific vocabulary. Additionally, long periods of intense concentration can lead them to fatigue.

Based on this research and first-hand account by someone who experiences brain fog, I believe Jargon(e) can play a role in improving the lives of people with brain fog.


As a system, Jargon(e) has three primary components:

  1. A browser extension that automatically annotates jargon on web pages with interactive tooltips
  2. Jargon repositories that store jargon and metadata such as tags and "learn more" links
  3. A web server that enables people access and share jargon repositories

Browser extension

The browser extension is written with a combination of web languages and tools: HTML, CSS, TypeScript, and React. This provides the logic and functionality to manage jargon repositories, find jargon definitions for a word, and render these definitions into existing web pages. This supports fast word lookups and re-rendering of content on pages with dynamically-loaded content.

Jargon repositories

Jargon repositories are JSON documents that contain self-describing information such as a name and source location as well as definitions and metadata associated with jargon. Importantly, the jargon repositories are decoupled from the browser extension and loaded into the extension by users. Anyone can create, host, and share a jargon repository over the internet. Even better: these jargon repositories can be dynamically generated and shared through a network-accessible API. This means that the people who host jargon repositories can tailor the responses that the user gets based on information like the current JSON schema version or information that users wish to share (like their preferred language or specific sub-categories of jargon they are interested in).

Web server

Although anyone can host a Jargon(e) web server, I created one as a proof of concept that the jargon repositories can be made available over the internet. The web server is running on NGINX and is currently available at `jargone.org`. The following URLs serve jargon repositories:

  1. https://jargone.org/extended_computing.json
  2. https://jargone.org/computing.json
  3. https://jargone.org/accessibility.json
  4. https://jargone.org/medical.json

Disability Justice Perspective

I had several disability justice principles in mind when designing Jargon(e):

  1. Interdependence: "We meet each other's needs as we build toward liberation, knowing that state solutions inevitably extend into further control over our lives."
  2. Collective liberation: "No body or mind can be left behind -- only moving together can we accomplish the revolution we require."

Jargon(e) addresses these principles directly.

With respect to interdependence, Jargon(e) is a community driven solution that encourages people to lean on each other and share knowledge. Jargon(e) repositories are de-centralized and offer a great deal of flexibility in terms of what jargon gets defined and the language that is used to define it.

With respect to collective liberation, Jargon(e) is a tool that helps to ensure that no mind is left behind. With inline jargon definitions, users of the extension can effortlessly move past language that would normally have the effect of gate keeping information. By sharing more of these definitions, we can eliminate more barriers to information access.

Learnings and future work

Through my work on Jargon(e), I learned how to use tools like Typescript and React to create and manage interactive and reactive components. I also learned that manipulating the document object model ("DOM") of other pages can be problematic since the developers of other websites will often write code that relies on a very specific DOM structure to work correctly. As a result, I spent a great deal of time identifying and resolving edge cases. Most notably, I had to handle edge cases and subtleties like: supporting dynamically loaded content without heavily impacting the performance of web pages; CSS style overrides; and not annotating the content that Jargon(e) had injected itself into the web page.

There are several things that I'd like to pursue in future work:

I'd like to make several changes to the components that my extension injects into web pages. Currently, there are some pages where the components don't render correctly. For example; the component may render underneath other content on the page; the CSS styles of the page may override some properties in the Jargon(e) component; or the component may render off screen. There are several solutions to these problems such as rendering the component inside of a "Shadow DOM," using an overlay effect to render in a layer above the page DOM, and using Javascript to move the component into the visible region of the page.

I'd also like to expand on the web server concept and implement a more robust web server that can help to score usefulness of definitions on specific pages and help the extension to prioritize more useful ordering of definitions.

How Jargon(e) is made accessible

Accessibility and ease-of-use are essential tenants of Jargon(e)'s implementation. I was intentional in the design of components to follow Web Content Accessibility Guidelines ("WCAG").

Principally, I used semantically accurate elements to represent the function of components on the page. Even though I wanted to override the visual representation of certain components, links are represented as links, buttons are represented as buttons, etc. To achieve the style for each component that I was aiming for, I used CSS to style built-in, semantically accurate elements. In cases where the button text, for example, was not a descriptive word for the action (and instead was a special character), I used aria-labels to define the semantic meaning of the button. As a result of this, interactive components (such as buttons) are keyboard accessible (with the short-term exception of initially opening the jargon definition popup).

Additionally, I wanted to be sure that Jargon(e) components were reactive. One way in which I did this was to add a loading indicator on the options page when a network request for a (potentially large) jargon repository is being made. Another way that I did this was by modifying the cursor design to a "help" or "question mark" cursor when the user hovers over an annotated word.

Another way in which I made Jargon(e) accessible was by avoiding jargon terms like "URL" and "protocol" in my error messages. I worked to make the error messages simple and actionable.

Finally, I wanted to reduce the amount of mouse movements that users need to make. To do this, I made it possible to close the jargon popup by clicking the annotated word a second time. I also moved the dialogue control buttons (such as "cycle definition" and "close") closer to where the users' mouses are when they click the word. These buttons render at the bottom of the popup when the popup renders above the word. I also made this layout reversible so that, in the future, when the popup can be rendered below the word, the controls will render at the opposite end of the popup with one line of code.


  1. "End-user moderation of cognitive accessibility in online communities: case study of brain fog in the lyme community"
  2. "What "Brain Fog" Feels Like"
  3. Disability Justice Principles
  4. WCAG Guidelines