Blog Home RSS Kelvin Jackson

Define Terminology Early in the Design Process

2023-08-30

Before you start coding, before you even start designing your project, it's important to define the terminology that you will use to talk about your project. While this may be an easier task for some projects than others, it can save you a lot of hassle down the line: misunderstandings due to different ideas of what a term means are costly in terms of developer and designer hours. While not every simple application requires a full custom dictionary, agreed upon and documented language is a must.

Often, agreeing on terminology for a project is relatively easy: a UI for a familiar type of service — say, a social network for people from a particular country — will consist mostly of parts that your entire team is already familiar with and able to communicate effectively about. As long as everybody knows what the goal is, they will probably be able to coordinate and make it happen without a lot of novel vocabulary building.

Things get harder, however, when the project is breaking metaphorical new ground in some way. If developers, designers, or any other stakeholders are not already intimately familiar with the type of software being developed, they may be unsure what to call parts of the UI/backend/etc, and communication is likely to be slow and awkward at best (and it may break down entirely at worst). You may end up with developers working on the wrong component, or building something completely different from what the designer and project manager (let alone the customer) actually asked for, requiring costly course corrections later when you had hoped that the work would already be mostly done.

Personally, I have lost many hours of work time combing through code trying to understand a particular feature and how I was supposed to extend it, only to realize that I had been asked to build something different from what I had assumed (or even a completely different feature entirely). While you can damage control this to some extent with frequent standups and checkins to make sure that progress is going in the right direction, an ounce of prevention is still worth a pound of cure: get the communication right the first time around, and many pain points of the work itself will simply evaporate.

In practice, there are various ways to do this. The projects I've worked on have mostly been simple enough that unclear terms could be resolved (or redefined) in a meeting with the other stakeholders, but that can get cumbersome quickly as a project grows in scope. In most cases, I would recommend setting up a glossary of sorts as part of your documentation (which you are writing, right?), and ensuring that all confusing terms end up there once their meanings have been pinned down. Then anyone with a question — and especially new team members — can be referred to a single source of truth for how to interpret unfamiliar terminology. Barring that, documentation showing all terminology in use can be enough to deduce the meanings of unfamiliar terms, but that is still risky — context is frequently imprecise, and your new developer may have a very different idea of the context than the person who wrote that particular bit of documentation.

Of course, there are no silver bullets in the real world, and miscommunications will always be a fact of life. However, by ensuring that every participant in every conversation is working with the same vocabulary, you can go a long way towards reducing their frequency to a more manageable level.