Date: November 9, 2019
Author: Daniel O’Neil
Reading Time: 2 min 40 sec

Summary: A structural vocabulary will help your project team make choices about design and implementation.

Oh project glossary, you archetype of stunted make work. In nearly twenty years on software development projects, I have never seen a project glossary be of value on a project—even those glossaries I’ve written myself.

My experience in trying to create project glossaries was that there was no way to know what was truly relevant for understanding, so there were only two ways to go:

1) Cherry-pick the words we THOUGHT would be useful, six months down the road, or
2) Try to capture every word. Every. Single. Possible. Word.

It is a kind of dark corporate comedy, reading those thirty page glossaries that include terms like “Operating System.” My heart goes out to the poor people who thought it had to be in there.

But the need is real. We know that language is structure, and that meaning is expressed through language. And it is no small thing, these breakdowns in language. Every software development project I’ve ever been on has encountered problems—sometime quite severe problems—because there was a misunderstanding about what a given word meant.

Therein lies the “why” that drives glossaries:  they are supposed to create a list of important words on a project that will make sure everyone is saying the same thing.

Yet almost without exception, they fail to do so.

Not a Glossary, but a Structural Vocabulary

The Understanding Group approaches the language question on projects with the assumption that the words are not enough:  they must be meaningfully arranged after mapping intent. In other words, we often don’t settle on a language for talking about a project until we have a better sense of what the project is really about. These words then become a core part of a strong design structure—so much so that we call the output of our work a Structural Vocabulary.

Structural vocabularies are, broadly speaking, comparable clusters of concepts about a design option. Dan Klyn often uses the architectural metaphor of “Ducks” versus “Decorated Sheds”, but interactive designers can create structural vocabularies for any interactive system. We could apply a structural vocabulary, to describe an eReader, for example, or a mobile game like Candy Crush.

The key thing about structural vocabularies is that they should help people on a project have discussions and make choices about design and implementation based on which cluster the idea seems to map to. Compared to a typical glossary, they are generally developed later in the project and developed against a more formal set of mapped intentions.

When we compare glossaries to structural vocabularies, some of the problems glossaries have become easier to understand:

• They are an attempt to map meaning before the map is drawn.

• We need to know too much, and we don’t know what’s relevant.

• The understanding changes over time so codifying things too early won’t work.

• They are not a core part of the design, so they tend to be forgotten.

Structural vocabularies address all of these issues.

Going back to our eReader/gaming structural vocabulary example, what would we get as potential structural vocabularies for the design and implementation phase? We’d get, in all likelihood, a few pictures and a collection of perhaps a dozen phrases, like the examples below.

eReader Structural Vocabulary

We are not trying to figure out every specification here. But this collection of terms gives us an opportunity to do some interesting thought experiments.

Game Structural Vocabulary

Let’s say, for example, that we are actually trying to build a music player. If we look at this list of concepts in each cluster, do we find ourselves thinking that the music app is more like an eReader or a game? What happens if we plug our design into each? How about a banking app? Is that more like a game or an eReader?

So for your next project, don’t sweat the glossary! But make sure you create as many defensible, useful vocabularies as you need to get understanding across your team.