Feature Glossary

When starting a new project you will encounter a lot of new terms, concepts and their relation to each other. The Feature glossary helps you to structure the flood on informations and give the project team a shared agreement on how things are called and what they are responsible for. It takes very little effort compared to its value.

All the nouns in the project

The goal of the glossary is get a sense of what things within a project exist and how they are connected. The act of writing the glossary raises a lot of intriguing questions I can then dive deeper into.

In the end you have a list of things, a brief description of each thing and how every thing is connected to other things in the project. The beauty of this glossary is, that it does can be done with any tool, everybody in the team can expand, correct it later on. Ideally located in a central place for the project it can serves as a ideal basis for discussions.

For this article I will use a simple toDo app as example, that has Tasks and Users.

How to write a glossary

Once I read through the supporting material like ticket, documentation, user feedback or my notes from the kick-off I already have some key things, I want to add the glossary, in my mind. At this stage I would consider this work to be only assumptions of the designer or design Team working on that project. So don’t be afraid of making mistakes. Can be corrected later, so let’s start or glossary:

1. Start by adding only the name of the things to the glossary. For me it is important that while I add things to the glossary I can see all other things that I have added already. In our todo app example we would add “Task” and “User” glossary to describe things.
2. Once you slow down adding new things it is time for the next step. Add brief description to things on your list.
3. Naturally you will use other terms from your glossary to describe things. This indicates a connection between them. In our case a user creates and completes a task. And we learn another thing by observing our description, that a user might have multiple tasks.
4. Sometimes, connections or new things are harder to spot. In our case a Task can be open or completed, which we could rephrase to be of Status open or completed. So we see that there is another thing hidden. This is the unpacking nature of this glossary exercise and why I am a big fan of this approach. Let’s add Status.
5. Give your colleagues access to the glossary, get their opinion, expand the glossary and descriptions.

Glossary done, what next?

Once the glossary is ready and up to date, you can use it as a starting point for the next step:

• Information Architecture Chart In complex situations when you have 12 or more things it makes sense to understand and draw out their relationship.
• Action catalogue Go through your glossary and add possible actions related to every thing. In our example: You can “Add”, “Delete”, “Rename” a task, “Change” the Status and so on. This is the perfect foundation for “Design Validation with Jobs to be Done” an upcoming article I am working on.
• Qualitative User interviews It makes sense to validate the Glossary with users if you are going to use the names from the glossary in the final product. This will reveal if the names for things are self explaining and if users generally have the same or a different mental model of the context.

When is it right time to write one?

From experience I find a glossary is the most impactful if done in the beginning of a project. It is a convenient time to establish the right names for things before it get’s harder to relearn used names. I start a glossary after the projects kick-off and reading the supporting material. Of course you will need to update the glossary over time. When starting a new project I am looking out for nouns, as these will be the items that are the starting point of our glossary. It is never too late to start one.

Onboarding new team member

Once the glossary is in place, a small introduction is written how the glossary should be interpreted it is a very good starting point for new joiners to get familiar with the project and to understand the fundamental concepts.

How did I come up with this approach?

In the past I had a particular difficult project in which people used the difficult terms like “WALT”, a lot. To give perspective WALT stands for “Weighted Average Life Time” and is used within commercial real estate to describe the weighted average remaining contract duration across all tenants within a building. We presented some concepts and the realtors constantly responded with, this is wrongly calculated it should be this other value.

I realised that different broker had different opinions by what dimension the weighting should happen. So I introduced “aWalt” , “rWalt” and “pWalt” weighting the Average Life time by area, revenue or profit. Once many industry insider realised that they had never articulated their implicit expectations and that other weightings could be really valuable in different scenarios.

It helped the team and it was much clearer how to calculate and to build once the definitions were set. So I repeated this definition for other values that needed clarification and as a team we felt we speak the same language.