As you start defining a common language, a glossary, in your organization, it can feel daunting to figure out the correct way to set it up. Since every organization's glossary is designed to reflect its unique style, it's natural that your glossary will look different. But following best practices in the implementation process will ensure that you set up a robust glossary that's right for your organization.
In search of the correct way of setting up glossaries, we distilled learnings from our amazing DataOps champions to design the broad guiding principles to follow while setting up a glossary in your organization.
Glossary best practices
Structure first, execution second
Before you start populating the business glossary with term definitions, make sure that you have agreed on the structure with all the key stakeholders. This means that you should have clarity on the type of glossary you want to start with — business-based, metric-based, technical, or project-based.
Once you are clear on the type of glossary, you should identify individuals who can take ownership of each part of the glossary. For example, if you are defining a metrics glossary that includes metrics from 5 different teams, ensure that you have at least one person from each team to take ownership. With these individuals, draft a broad structure where you can brainstorm terms for each team and assess their fit for your MVP.
Treat a glossary as a product
Whatever type of glossary structure you choose, remember to treat your glossary as a product. What that means is that every term in the glossary should be designed keeping the end user's value in mind.
- Reusable and accessible: Every end user, whether an analyst, business stakeholder or data engineer, should be able to understand what a term means. They should be able to refer to this context in their day-to-day work.
- Well-documented: You should assess what needs to be included in your glossary term to create the maximum impact. For example, you can decide that it should have:
- a business definition in the description,
- any gotchas captured in the README, and
- calculations (if any) linked as saved queries.
- Scalable: A glossary should be designed for the entire organization's needs, not just 1-2 users. That's why it's essential that you spend some time upfront deciding on a structure that will scale as your data maturity grows over the years.
Choose your implementation approach
When it comes to implementing a glossary structure, you need to find an approach that works for your organizational dynamics. Some factors that would influence your implementation process are the size of the organization, the number of data owners, and the data maturity of the team. Below, we've shared three broad implementation approaches we have typically observed.
Data Definition Expert
In this approach, you implement a glossary by having a dedicated data definition expert. Especially when you have smaller data teams where 1-2 people have all the context, this expert can take ownership of implementing a glossary in a sprint.
Team of SMEs
The other way of implementing a glossary is more centralized. You assign terms by category owners/data sources. In medium to large teams where context is spread across multiple people, this approach can be really effective. A key factor for success with this approach is clearly identifying owners and assigning responsibilities. If you plan to use this approach, ensure that all the contributors have a clear idea of ownership across terms.
When context is so far spread out in the team that it's hard to identify owners, you can use dedicated documentation hours to crowdsource terms. Once you agree on the broad structure of the glossary, you can also use gamification to populate the terms in a few sprints.