Project Glossary

PDF Link

Project glossary defines the meaning of the vocabulary appearing in the software project. It ensures different users to maintain the same understanding when reviewing the software design artifacts.


What is a project glossary?

Project glossary allows us to define a standard meaning of a particular vocabulary or phrases inside the software design artifacts, such as information captured in requirements, design diagrams, documents, etc... People with different background or perspective could have different understanding when they read on the same piece of information. Consider the following statement:

Customer can remove his/her account permanently by mailing us an account removal form.

Let's focus on the word account in the statement, what does it means? To a user with banking background he associated it as a bank account, but for a service provider this could mean the customer account for subscribing a particular service. This kind of ambiguity could causing serious communication issue between different parties involved in a software project, thus it could result a disaster as the incorrect interpretation of software design artifacts.

The project glossary is a collection of vocabularies or phrases (the terms) captured from various models, reports and any other artifacts in the software project. Each term are defined with its meaning specific to the project domain. By defining project glossary, it unifies the vocabularies from different sources into a standard meaning for different parties, that serves various different of purposes for project development:

  1. understand the design artifacts
  2. provide description to key terms and phrases
  3. explain detailed concepts
  4. describe abbreviation, etc...

How to define project glossary?

Project glossary can be defined by reviewing and standardizing all the terms used from different models and artifacts in your project, including the requirements obtained from users, meeting notes, design specifications, test plan, etc... You can put all the identified terms into a list and then give them the meaning. Once complete you got a full list of terms used in your project. Everyone can refer to it when reviewing the project artifacts, which can avoids ambiguity causing by interpretations of a term from different stakeholders or using different expressions for the same terms.

Project glossary

Link up similar terms with Alias

Sometimes multiple terms captured could meaning the same concept. In this case we can select one as the glossary, and have the rest defined as its alias. This help to make sure user can find the correct meaning to the term even it is different to the glossary being defined, without define the same meaning over and over on all the similar terms.

Alias

Organize related terms together

For a complex project it could come up with thousands of glossary terms. Even if the terms are sorted in in order, it could be still very difficult and time consuming to looking up. We can organize the terms according its context that make terms easier to be looked up and located.



Visual Paradigm supports defining project glossary for your models, which allow us easily find the meaning of the glossary terms in your project.

References

  1. Learn about glossary management in Visual Paradigm
  2. Tutorial - Glossary Team Identification from Business Process Model