Glossary

In a recent talk, I asked the audience of about 100 BAs which of them maintained a glossary as part of their work.

glossary

About 20 hands went up. 😦

I was almost embarrassed to even ask the question – it seems so obvious – so the answer was even more of a surprise. So 80% of the audience didn’t think it was important that we all agreed what we were talking about.

If you find a BA of long experience (or a process analyst, or a modeller of any kind) and they will almost certainly have a story of ‘how I looked an idiot because I mis-understood the terms they were using‘.

Mine was many years ago, running a workshop for a debt factoring company. The task was to create some use cases for a new admin system, and quite frankly, the first morning was bad. There were lots of puzzled looks in the meeting, even though these were a  crowd of smart business experts. So I fell back on the trusted approach – if technique A doesn’t work, try B. And my default ‘Plan B’ technique is ‘create a domain model’ : really just an enhanced glossary. When we got to the bit about “Customer/Client” – which I had been using interchangeably all morning-  and I asked ‘about how many customers/clients do you have‘, I was stunned by the reply – “5000 clients, and 5M customers‘ (maybe it was the other way round – was too stunned to think straight)

WHAT!

Customer” = “Client” – right ?

Wrong.

In their world, they are as different and up & down. Lesson learned. When writing use cases, or requirements, or anything which uses business language, create at least a glossary, and if possible, a domain model at the same time.

And make the glossary a managed knowledge asset like all the others. Make sure to record where definitions came from (see Provenance) and don’t let people randomly change definitions just because they think they have a better idea. And include it in documents, with references, so everyone gets used to the idea of a common set of terms.

<sales pitch>

<pitch eaDocX, the document generator for Sparx EA which I write has a feature of looking at the terms in a document, and generating a glossary consisting of only the terms used in that document. Stops the glossary from becoming over-sized./>

</sales pitch>