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


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)


Customer” = “Client” – right ?


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>

About the Author Ian Mitchell

Ian Mitchell is a business analyst and software developer. He's been using UML since before it was UML, and has managed teams of BAs all over the place. He also teaches UML and BPMN, and writes the eaDocX document generator for the Sparx EA tool.

One comment

%d bloggers like this: