In typical models, words like user, account and customer often appear as names of model elements or part of model elements' descriptions. Actually, what exactly do they mean? Are they all referring to the same thing or concept? It is a question that no one except the end user of the system, the system analyst and perhaps the developer can provide you with an answer. We are aware that the meaning of words used in models may vary depending on the system domains, the contexts and the users. Therefore, defining keywords is vital to help building a common understanding of vocabulary used within a project and among the team members and end users. The glossary in Visual Paradigm is where you can add and define terms and phrases. Clear definitions not only can avoid ambiguity, it is also a benefit from which developers can reap and reduce the chance of developing "misbehaved" functions.
Although having a glossary is a great thing, building one can be challenging. To build a glossary, you must ask yourself a question, 'What are the important words and phrases that need to be defined?'. You might randomly think of one word or two easily but over time, you will find it getting harder and harder to gather words and phrases that are really important or relevant to the system. A recommended approach would be to start from a domain class model.
Domain class model is developed at the early stage of system development. It aims at capturing and representing the concepts and relationships in the domain. For this reason, it can be understood by both the end user and project team. The vocabularies used in a domain class model are supposed to be meaningful, important and relevant to the system from the user's point of view. Therefore, domain class model is always a reliable starting point in identifying glossary terms.
Case Study: Develop Glossary for an Enquiry Management System (EMS)
The True Aqua Distilled Water Company is a distilled water supplier in the city. The company receives tremendous amount of user enquiries daily and the management wants to employ an enquiry management system to improve users' satisfaction. You are a system analyst and your development team is responsible for developing the enquiry management system. Now, follow the steps below to develop the domain model and derive the glossary from the model.
- Create a new project with Visual Paradigm. Select Project > New from the application toolbar.
- In the New Project window, enter Enquiry Management System as project name. Click the Create Blank Project button.
- Create a class diagram by selecting Diagram > New from the application toolbar. Select Class Diagram and click Next.
- Enter Domain Model as the name of the diagram and click OK to confirm.
- Think of the concepts of the system and list them out in the form of classes. Here are the classes listed: Customer, Enquiry, Enquiry Type, Customer Service Assistant
- Connect the classes (concepts) with proper relationships.
- The domain class model is completed. Now, derive a glossary from the model by adding the names of classes as glossary terms. Double click on the Enquiry class. Right-click on Enquiry and select Add "Enquiry" to Glossary from the popup menu.
- You should see a message appears on the status bar, telling you that the term Enquiry has been added into the glossary grid. Click on the link of glossary grid to go there. If you have missed that, do not worry. You can open the glossary grid by selecting Modeling > Glossary > Glossary Grid from the application toolbar.
- Glossary grid is where glossary terms are listed. You can check the terms and their definitions in the grid. You can also create and manage terms via the related function buttons on the toolbar at the top of the glossary grid. Now, describe the term Enquiry. Right-click on the term and select Open Term Editor from the popup menu.
- Enter the definition of term in the Definition field: A request of support issued by customer, with question or problem described.
- We can use different words to refer to the same term. This helps to avoid redundancy in creating multiple terms carrying the same meaning. Let's say some of the end users may call an enquiry a "support request." Let's add an alias called "support request". Click Add on the right in the Aliases section (which is located at the top of the term editor).
- Enter Support Request in the input window and confirm. Support Request is now an alias of the term Enquiry.
- Go back to the glossary grid by selecting Modeling > Glossary > Glossary Grid from the application toolbar. You can see the alias and description (i.e. definition) as well.
Now, add the names of the other classes as terms:
Name Aliases Documentation Enquiry Type Enquiry Group The kind of question or problem described in the enquiry. Customer Client The person who submits an enquiry. Customer Service Assistant The person who is responsible for answering an enquiry
Different readers may be interested in reading a project from different angles. To help categorize these angles, labels can be defined. Glossary terms can then be tagged by labels and filtered for listing purpose.
Now, let's define a term with a label. Click on the Labels cell for the term Customer in the grid. Click on the plus button at top-right corner.
- In the Add Label window, click New Label... at bottom left. In the popup window, enter the name of the label: Human. Select a color you like and click OK to confirm.
- Click OK in the Add Label window. The label is added to the term.
- Labels can be used in filtering terms to be shown in grid. Click on the Configure Grid button.
- Select With Label... for Scope.
- Check Human in the Scope window and click OK. Now, only Customer is listed in the grid.
- Change the scope back to Project. All terms are listed.
- Go back to the class diagram. You can see that the names of the classes are all highlighted. When a reader wants to know what a class name means, he can open the definition from the class. Move the mouse pointer to any underlined text shown in the diagram. Press the <Ctrl> key and click on the word. This opens the glossary grid with the term highlighted.
Export Glossary to Excel
The term definitions can help modelers in the same team to establish and maintain a common set of vocabularies when modeling and communicating with each other. You can also make use of the Excel export function to produce a soft copy of the glossary and share it with other team members.
- Open the glossary grid.
- Click the Export to Excel button from the toolbar within the grid.
- In the Export Excel window, specify the output path to save the Excel file in.
Keep the other settings unchanged. Click Export at bottom right.
As a side note, importing changes made in Excel back to the glossary in Visual Paradigm is possible. If needed, readers of the glossary can make changes in Excel. After that, simply click the import button in the glossary grid (in Visual Paradigm) to import the Excel file back to Visual Paradigm. The import button is next to the export button.