Building a Website That Explains Its Own Language
One of the last pieces of this website redesign started as a writing problem.
I wanted a glossary: somewhere to explain the technical language I use all the time. If I mention a canonical URL, a content model, a channel manager, an API, or a RAG system, someone who doesn't work with those things every day should still be able to find out what I mean.
The question underneath that was simpler than it first looked. How do I write about technical work for a mixed audience without stopping every second sentence to explain myself, and without assuming everyone already speaks the same language I do?
The Problem Wasn't Technical Language
There is a temptation, especially when writing for non-technical audiences, to strip the technical language out entirely. Sometimes that's the right choice. There is no reason to call something an API if the distinction doesn't matter to the person reading the page, and there is no prize for fitting the most acronyms into a paragraph.
Sometimes the technical term is the useful term. If I'm talking about the difference between a Booking Engine, a Channel Manager, and a Property Management System, replacing all three with “booking software” removes the distinction I'm trying to explain. The same thing happens with Authentication and Authorization, a Payment Gateway and a Payment Processor, or an XML Sitemap and a Visual Sitemap. Those words exist because the things they name actually differ.
The trouble starts later, when a page has nowhere appropriate to put that explanation. I can stop and define the term:
A channel manager is a hospitality system that distributes rates and availability between a property and multiple booking channels...
or I can move on and assume you already know. Pausing for a definition can turn a service page into a textbook, and skipping it can make useful information feel unnecessarily exclusive.
The glossary gives me somewhere in between. I can write:
Your booking engine and channel manager need to agree about availability.
People who already understand those systems keep reading, and everyone else has somewhere to go. A service page can stay at one depth, a glossary entry can take the next step, related terms can take someone further, and a longer article or whitepaper can go deeper still. Different readers can choose how far they want to go without being forced through all of it on the same page.
That's especially useful because the audience for this site varies considerably. One person may be another developer trying to understand how I approach a CMS migration. Someone else may run a small tourism business and only wants to understand why their room availability keeps disagreeing between their website and Booking.com. They don't need the same explanation at the same moment, and they should still be able to use the same website.
A Definition Has to Do More Than Expand the Acronym
Giving a term its own page only helps if that page is actually useful.
API: Application Programming Interface.
You can know what the letters stand for and still have no idea what the thing does in a real project.
Most glossary entries on this site still move through some version of what it is, how it works, why it matters, what commonly goes wrong, and which other concepts sit nearby. The exact headings change because the concepts change. A definition of Colour Contrast needs different context from a definition of Inventory Sync.
What stays consistent is the editorial standard: by the end of the page, you should understand enough of the concept to recognize it in a real project, and to have a better conversation about it. Each page should get someone from “I've heard that term” to “I understand what role that plays.”
The Glossary Became Shared Vocabulary
At some point I realized I wasn't only building something for website visitors. The same words show up in articles and in conversations with clients.
We might be talking about whether a site needs a CMS Migration, why a page has become an Orphan Page, whether an integration should use a Webhook or Polling, or what Technical Debt actually means in the context of an existing site.
I can explain those things on a call, and afterward send the client to the exact version of the concept I'm using: my definition, in the context of this work, connected to the related ideas that actually matter here. That is a different thing from asking someone to remember the conversation perfectly, or to Google a generic definition that may describe the same words in a completely different context.
It also forces me to be consistent. Once Website Architecture, Technical Debt, CMS Migration, Conversion, and Website Ownership have an established meaning, I don't get to redefine them slightly every time I write a proposal, an article, or a follow-up email. The glossary has become a language system for the work: a shared vocabulary I can use with clients, and a check on whether I'm using those words the same way I used them last month.
Once the Terms Connected, the Glossary Became Architecture
A few terms were never going to stay a list. API, Authentication, and Authorization belong together, and APIs & Integrations gives them a shared context. Channel Manager makes more sense beside a PMS, an Online Travel Agency, and Room Inventory than it does in an alphabetical dump of every term on the site. Website Performance connects naturally to Core Web Vitals, Caching, and CDNs.
Those collections connect to one another as well. A hotel Booking Engine can lead into Checkout, which leads into Conversion, Website Accessibility, Analytics & Measurement, and Website Performance.
Plenty of terms could reasonably appear in several places, which is why I generally give a concept one main home and link back to it elsewhere. A Product Feed can use Structured Data without E-commerce needing a second definition of structured data. Room Inventory deserves its own page because accommodation inventory behaves differently from physical product inventory. Concepts need one clear home, and they should still be able to participate in several systems.
That is the point at which the glossary stopped being a reference page and started working like a map. Very few problems stay neatly inside one discipline: a “website problem” might actually begin in DNS, a “checkout problem” might be an inventory integration, a “performance problem” might be a third-party script, and a “content problem” might really be an architecture problem.
Building it has also made visible something I tend to do in project work anyway: take a messy technical system, separate its parts, establish what each one is responsible for, and explain how they connect.
That Structure Makes the Rest of the Site Stronger
Once the glossary had that structure, it started making everything around it easier to build.
Service pages can stay focused because the prerequisite concepts already have somewhere to live. Articles can send a curious reader to the exact idea that just became relevant, instead of stopping to establish vocabulary. Someone reading about APIs should be able to follow the concept into Authentication when authentication matters, and a page about e-commerce can connect to Checkout or Inventory Sync without turning into a textbook.
The SEO benefit is downstream from having a better-organized body of information. The glossary creates a lot of meaningful Internal Links, and those links give search engines more paths through the site, but the links earn their place when the relationship is actually useful.
There is a selfish version of the same effect. If I'm writing about a site migration, I can use Redirect, DNS, Staging Environment, CMS Migration, and Canonical URL without rebuilding the prerequisite explanation every time. If I find myself linking to the same glossary concept repeatedly, that may be a sign the topic deserves a larger article, playbook, case study, or whitepaper. The glossary has become part of how I plan what to write next.
If It's Infrastructure, I Have to Maintain It
If I intend to rely on this across articles, client work, internal linking, and the rest of the site, it has to stay trustworthy. A reference stops being useful pretty quickly if I have to wonder whether I still agree with it before sending it to someone.
Terminology changes, platforms change, and standards evolve. AI vocabulary is moving especially quickly, analytics products rename things, and a feature that once needed a complicated integration may eventually become native. Internal links can break, external references can go stale, and definitions can become technically correct but practically stale.
So the glossary has joined the list of things on this website that need Maintenance. That is the cost of relying on it this way.
A Website That Can Explain Its Own Language
I don't have to make every page explain everything. I need the site as a whole to make the explanation available.
That's the job I wanted the glossary to do: make the ideas underneath those technical words easier to understand, so the words themselves matter a little less.