RFD Glossary Feature

[hermanol]

Summary

The current search experience on the RFD site is limited to literal string matches in titles (on the homepage), title + content search (available from the top right), and label‑based filtering has limitations as the body of work grows (60+ public RFDs, many more internally). A lightweight, hyper‑linked glossary would give users an entry point to discover related documents, understand domain‑specific terminology, and navigate the knowledge base more efficiently.

---

Motivation

Problem	Impact
Search and Filtering – Searches titles and RFD contents, but does not surface documents in a way that puts forth context in an opinionated way.	Users spend more time locating information relevant to their immediate questions.
Label filtering – useful for small sets but becomes unwieldy with thousands of RFDs.	Discoverability degrades as the volume of content increases.
Implicit term relationships – many RFDs reference each other without an explicit map.	Contextual understanding of abstractions is low; newcomers face a steep learning curve.
Verification & veracity – existing references are not centrally curated, leading to stale or duplicated definitions.	Incorrect, outdated, or overloaded definitions can propagate and cause confusion.

A curated glossary could help to address these gaps by:

• Providing a single source of truth for definitions.
• Enabling hyper‑textual navigation (terms link to definitions and to every RFD that mentions them).
• Offering default filters (e.g., exclude abandoned RFDs, show only discussions with full context).
• Being lightweight and low‑cost to generate and maintain, especially when powered by LLM pipelines, which don't increase the existing site footprint.

---

Goals

1. Ease of Use – Users can locate a term and jump directly to all relevant RFDs within two clicks.
2. Improved Discovery – Increase the rate at which specific topics are found without expanding the UI complexity.
3. Scalable Maintenance – Automate glossary population and updates as new RFDs are merged.
4. Foundation for Future Features – Enable downstream enhancements such as ontology building, customer‑facing knowledge bases, and richer knowledge‑graph queries.

---

Proposed Solution

1. Glossary Data Model

Store each term as a discrete JSON‑LD file (or equivalent) following the schema below:

{
  "id": int 
  "term": "string", // term name
  "definition": "string", // what the term means
  "mentions": [{ "number": int, "text": "string"},]  // RFDs where this term comes up
  "relatedTerms": [{"id": int, "term": "string"},] // Other terms in the glossary related to this one, or included in the definition
  "references": [{"url": "string", "text": "string"},] // external links distinct from the RFD site that provide additional context
  "public": bool // whether a term appears in public RFDs, and thus a public glossary.
}

These term files could be placed in a new glossary.d/ directory, and segmented by first letter (A/term.json, B/term.json, …) This could look something like this:

hermano /rfd-site glossary !? v16.20.1 17:04 ls -l ./glossary.d/ | head -n 5
drwxr-xr-x@ 11 hermano staff 352 Dec 29 15:45 A
drwxr-xr-x@ 9 hermano staff 288 Dec 29 15:45 B
drwxr-xr-x@ 9 hermano staff 288 Dec 29 15:45 C
drwxr-xr-x@ 10 hermano staff 320 Dec 29 15:45 D

hermano /rfd-site glossary !? v16.20.1 17:04 ls -l ./glossary.d/C
total 56
-rw-r--r--@ 1 hermano staff 434 Dec 29 16:16 cerberus.json
-rw-r--r--@ 1 hermano staff 568 Dec 29 16:16 cosmo.json
-rw-r--r--@ 1 hermano staff 316 Dec 29 16:43 cpld.json
-rw-r--r--@ 1 hermano staff 137 Dec 29 16:16 cpu.json
-rw-r--r--@ 1 hermano staff 139 Dec 29 16:41 cru.json
-rw-r--r--@ 1 hermano staff 340 Dec 29 16:59 crucible.json
-rw-r--r--@ 1 hermano staff 669 Dec 29 16:43 cubby.json
	

This has the benefit of avoiding possible merge conflicts as terms are updated with newly published RFDs, and could also enable future-state contextual enhancements like term highlighting (we'll get to that later) in subsequent improvements in a manner that's cheap and efficient.

2. Content Generation

• Initial population – Use the existing engineering glossary (internal) as seed data.
• Incremental updates – Implement a GitHub Action that runs on every PR affecting an RFD. The action:
  • Invokes an LLM (e.g., Claude Sonnet 4.5) with the diff to extract new/updated terms.
  • Updates the corresponding JSON files in glossary.d/.
  • Commits the changes back to the repository.

The RFD API (github.com/oxidecomputer/rfd-api) can be leveraged to retrieve full document text for context when generating definitions, and @plaidfinch has made a working example of this in an internal repository.

In line with our values as expressed in RFD 576 - Using LLMs at Oxide, we would want to take great care to ensure that we leverage the strength of LLMs to soak up written context, compared to its relatively weak writing abilities. To this end, we should rely on human approval of definitions to guarantee veracity. In other words, final definitions should be human-written.

3. Appearance

• Add a top‑level Glossary (e.g., in glossary.tsx) page to the RFD site that lists terms alphabetically.
• Each entry links to its JSON definition and to a list of RFDs where the term is mentioned.

This could look something like this:

• Textual highlighting for glossary terms within the body of RFD documents:

---

Risks & Challenges

1. Completeness – Automatic extraction may miss nuanced terms or generate duplicate entries. Having a human in the loop for manual review of PR‑generated changes could help this.
2. Performance – Loading large term lists on every page could affect load time. This could be mitigated with lazy loading per initial letter and caching of generated JSON files in glossary.d.
3. Maintenance Overhead – Ensuring the glossary stays in sync with evolving terminology. This could be helped by the aforementioned GitHub Actions runner for all RFD PRs; along with a potential periodic audit of terms and definitions.
4. Security / Privacy – Some terms may reference internal components not intended for public consumption. The use of a public flag in the schema to establish public and private versions of the glossary should address this.

---

Acceptance Criteria

• A public Glossary page is reachable at /glossary and lists terms alphabetically with links to definitions and mentions.
• A glossary.d/ directory exists with at least the initial seed terms (minimum 20 entries).
• A GitHub Action triggers on every RFD PR, extracts new terms, and updates the JSON files.
• Hover‑over tooltips for known terms appear on RFD pages when the optional JS is enabled.

---

Limitations

This does not a knowledge management framework make. While this could be an incremental step in helping staff and friends of Oxide to come up to draw deeper into the deep information resources that have been built up over time, this feature would strictly extend the existing features of the RFD static site.

An eventual target might be a more robust data layer for knowledge and customer context, but this should make for a lightweight, low cost model for relevant and effective information sharing. If this goes well, it could be extended into building other ontologies for system issues, customer engagements, etc, which at that point could probably use its own RFD!

---

Roadmap

Phase	Description
Phase 1 – MVP	Static glossary page, JSON‑file storage, GitHub Action for updates, optional tooltip integration.
Phase 2 – Enrichment	Add relatedTerms, external references, and richer metadata; introduce a searchable endpoint (e.g., /api/glossary).
Phase 3 – Term Highlighting	Within individual RFD pages, employ a lightweight client‑side set of functions that a. Loads a minified glossary.json (or a.json, b.json, … on demand), and b. Replaces occurrences of known terms with hover‑over tooltips linking to the glossary entry.

---

References

• RFD API – https://github.com/oxidecomputer/rfd-api
• JSON‑LD Specification – https://www.w3.org/TR/json-ld/
• GitHub Actions Documentation – https://docs.github.com/en/actions
• Claude Skill for GitHub Integration – https://code.claude.com/docs/en/github-actions

---

[david-crespo]

We do have a full-text search button in the top right. Discoverability of the button could be a usability issue, and of course relevance and presentation in the results can always be improved. Talk to @plaidfinch, who did a lot of exploration on glossary generation a few weeks ago. Here's an example glossary that came out of that: https://gist.github.com/david-crespo/021eb23aa64c5b20e5487a381113e6b0.

I am personally skeptical of the value added by a static glossary (even one automatically kept up to date) over live search + LLM synthesis. The latter would have the advantage of automatically being scoped to what a given user is allowed to see (you point this out as a challenge with the glossary). In order to use LLMs we would have to do some work on oxidecomputer/rfd-api#363 to avoid sending NDA'ed content to them.

As you can see from the linked example glossary, with a corpus this large and dense, there is a very significant tradeoff between being comprehensive and being focused and usable. A static glossary would essentially amount to a cache of answers to questions you might otherwise use search (+ optionally an LLM) to answer. Maybe it's true that that's easier to implement than other ways of making these questions answerable through the site (e.g., direct LLM integration into search), but I don't want to prejudge that and say a glossary is the solution.

Note also that a glossary that lives in this repo doesn't make sense — if we were going to do this it would have to be by first-classing the concept in the RFD API and storing the data in a table.

[hermanol]

Whoops, you're 100% right on the contextual search. I've gone ahead and updated the OP to account for that, I hadn't noticed that the search in the top right was searching the RFD headers and body text in addition to the titles, that certainly helps.

I do think that integrating 'Ask a question' functionality into docs is often a good idea, I have some notes drafted for how that could fit in to the user guides site, though I've had a lot of success with implementing chat into our internal docs at my previous company with an off-the-shelf solution (Gitbook). It was great being able to ask questions of our documentation using natural language, and it came in handy during onboarding more than once.

I think that a glossary could have a different value proposition though, in terms of bringing an aspect of discoverability (searching the glossary, rather than the whole corpus) and authority (it's human written and has verified sources, so I may be inclined to trust it more), just to name a couple examples.

[hermanol]

After some discussion, I'd like to float the idea of a glossary component as being much smaller than I initially laid out, composed of two features which could be disabled on a given site deployment, for example:

1. Glossary static page (on/off)
2. Textual context highlighting (on/off)

Where the facility for updating references and determining access lies in the rfd-api (for example, in the form of an additional /glossary component) and something like an RFD language server for wrapping those capabilities, see here: https://github.com/oxidecomputer/rfd-tools

In this way, entries in the glossary.d directory mentioned above would not be shipped with the rfd-site repo, and instead be populated as needed.

[hermanol]

To tack on a bit more information insofar as where this might fit in with other improvements internally, this would be intended to be complimentary to:

1. Tagging all RFDs: https://github.com/oxidecomputer/rfd-labeler
2. Semantic Search Improvements: I couldn't find an issue but see above observations on current Meilisearch output
3. Contextual search: Add Claude Code skill for RFD research rfd-api#362
4. Reading Lists (possibly along the lines of something like): https://github.com/oxidecomputer/docs/pull/606

There may need to be a forthcoming RFD on the topic.

[augustuswm]

There are definitely a lot of improvements to be made here. I would like to take a step back and try to answer what the use cases that we are trying to satisfy here. Effectively we can add whatever features we want, but what are we solving by implementing them. I know we have issues around discoverability, and information volume, but putting them down as actual statements and how these updates may solve or improve them would be very helpful.

[hermanol]

There are definitely a lot of improvements to be made here. I would like to take a step back and try to answer what the use cases that we are trying to satisfy here. Effectively we can add whatever features we want, but what are we solving by implementing them. I know we have issues around discoverability, and information volume, but putting them down as actual statements and how these updates may solve or improve them would be very helpful.

I think you're right. I'm going to put this feature on pause for now, and start drafting an RFD for the much broader topic of knowledge transfer and information sharing. I think the primary focus would be:

1. Laying out the variety of ways in which information is shared currently, from onboarding onwards
2. Defining the problems that this current landscape poses along the axes of:
   1. Discoverability
   2. Interactivity
   3. Relevancy / Depth of detail
3. Describing some of the ideas and new implementations that have been introduced so far
4. Posing the question of where these might be lacking, and what complementary new solutions or processes might look like