There is a particular kind of mistake that nobody notices until it is too late. It does not come from bad intentions or poor planning. It comes from two groups of intelligent people sitting in the same meeting, using the same words, and meaning entirely different things.
The business owner says “customer.” The developer writes it down. The meeting ends, and everyone leaves feeling that something useful was accomplished. Six weeks later, when the first version of the software appears, it becomes clear that what the developer built and what the business owner imagined share only the word — not the meaning. The customer records do not include the right fields. The status labels do not match the workflow. The reports pull the wrong data. Fixing any of it means unpicking decisions baked into the database structure from the very first day.
This is the dangerous gap between business language and developer language. It is one of the most common sources of rework, delay and frustration in software projects — and one of the easiest to prevent, once you know it exists.
Familiar words are often the most dangerous ones. Precisely because everyone thinks they already know what a word means, nobody thinks to check.
Why Familiar Words Are the Most Dangerous
Specialised technical jargon is rarely the problem — when a developer uses an unfamiliar term, you ask. The gap gets closed immediately.
The real danger is the vocabulary you both already use. Words like customer, order, account, status, approval, product and contract appear in almost every business context. They feel unambiguous. They are not.
In a business owner’s mind, “customer” might mean anyone who has ever placed a paid order. In a developer’s mind, it might mean any user who has completed registration — whether or not they have paid for anything. In the database, these two definitions produce entirely different structures. One version has customers linked to invoices from the start; the other does not. The business discovers the problem when it tries to run a report on repeat buyers and finds the data simply is not there.
Neither person was careless. Both were operating from a reasonable assumption. The word looked shared. It was not.
Terms That Commonly Cause Confusion
Across many different types of business software, the same categories of terms tend to cause the most trouble. Some examples worth watching for:
- Customer vs. contact vs. account vs. user. Is a customer a company, a person, or a login? Can one company have multiple users? Each answer implies a different data model.
- Order vs. quote vs. booking vs. job. At what point does an enquiry become an order? Is a quote a separate record or a version of an order? Your business language may not map cleanly onto the states a developer assumes.
- Status. This single word can mean a workflow stage (“pending,” “active,” “closed”), an operational state (“online,” “offline”), or a payment state (“invoiced,” “paid,” “overdue”) — sometimes all three, on different records in the same system.
- Approval. Does it mean one person signed off, or a group all agreed? Is it logged? Is it reversible?
- Product vs. service vs. item vs. SKU. In retail these have agreed meanings. In service businesses they often do not. A “product” might be a fixed-price deliverable, a subscription, or a bundle of several things.
None of these are trick questions. They are what your developer needs answered before writing the first line of code — and they tend not to get asked precisely because the words feel too obvious to query.
The Value of a Short Project Glossary
The solution is not complicated. It is a short document — sometimes just a single page — that lists the key terms your project will use and gives each one an agreed, written definition. This is a project glossary.
A useful glossary has three columns: the term, what it means to the business, and what it means in the software. Where those two meanings differ slightly, the third column records the agreed definition that will govern the project going forward.
The glossary does not need to be exhaustive. Five to fifteen core terms — the ones that appear most often in your requirements, your workflows and your reports — is usually enough to prevent the most damaging misunderstandings. The exercise of writing it forces both sides to articulate assumptions that have never been stated out loud, often for the first time.
A project glossary is not a bureaucratic formality. It is the moment when a word stops being assumed and becomes agreed.
Building the glossary together — business owner and developer in the same conversation — is more valuable than either side producing one independently. The disagreements that surface during that conversation are precisely the ones that would otherwise surface as bugs, three months later, in a system that is already live.
Why Definitions Must Include Examples and Exceptions
A bare definition is rarely enough. The real content of a business term often lives in its edge cases.
Consider “active customer.” A definition might read: “A customer who has placed at least one paid order.” Clear enough — until you encounter a customer marked dormant by your sales team, or one with a current quote not yet confirmed. Each edge case becomes a small decision made in isolation by a developer trying to be helpful, who may choose differently from how the business would. Over a full project, dozens of these small decisions accumulate into a system that behaves slightly but persistently differently from what was expected.
When you define a term, ask: What is the most confusing version of this? Write it down. Then decide the correct answer. That decision belongs in the glossary — not in a developer’s head late on a Tuesday evening.
Keeping Terminology Visible Throughout the Project
A glossary written once and then filed away is only half useful. The value comes from keeping it visible and live throughout design, testing and handover.
During design, screen labels and field names should use the agreed terms — not synonyms or developer shorthand. If the glossary says “booking,” the screen should say “booking,” not “reservation” or “appointment.” That consistency is what makes a system feel coherent to the people using it.
During testing, the glossary provides a useful check: any label or report heading that does not match an agreed term is worth querying. The mismatch might be cosmetic; it might also signal that a concept has been built differently from how it was defined.
During handover, the glossary becomes part of the documentation. A new developer joining the project inherits not just code but the shared understanding of what the business means by its own words. Without it, they are guessing.
Practical Steps to Close the Language Gap
- Start before the build does. Produce the glossary during requirements gathering. Terms baked into a database schema early are expensive to change.
- List the words you use most often. Every noun that refers to a record, a person or a state in your business is a candidate.
- Write definitions in plain sentences. “A customer is a company or individual who has placed and paid for at least one order” is clearer and more testable than “someone who has bought something.”
- Add at least one example and one exception per term. The example makes the definition concrete; the exception prevents the most common misapplication.
- Review it with your developer before build begins. Any term that prompts a question is a gap that would have cost you later.
- Keep it somewhere shared and findable. A Notion page, a pinned Google Doc, a Confluence article — format matters less than accessibility.
- Update it when the language changes. Language drift is normal; undocumented language drift is a risk.
The goal is not to turn your business into a dictionary. It is to make the implicit explicit — so that the software you commission actually reflects the business you run.
A Small Investment With Outsized Returns
A project glossary for a typical small business application takes two or three hours to produce. Compare that with the cost of discovering, six weeks into development, that “customer” has been built as a different concept from the one your business runs on. Unpicking a database structure is not a small job. The glossary does not guarantee a perfect project — nothing does — but it removes one of the most reliably expensive sources of rework, quietly, early, and for almost no effort.
Start with five words: the ones that appear in your invoices, your emails to clients, your internal reports. Write down what each one means to you. Then ask your developer what it means to them. If the answers match, move on. If they do not, you have just found a problem that would have cost you money — and found it before it was built into anything.
