Product development documentation is intended to exchange information with every team member who should be aware of what’s being built. I’ve seen many articles describing the author’s list of “essential documentation for effective product delivery.” But one document that often comes up missing from these is a project glossary.
What Is a Project Glossary?
A project glossary is an alphabetical list of words (and abbreviations) used in the project, along with their meanings. It’s not a difficult concept to grasp, but I’ve often heard teams try to pass off other types of documentation as a project glossary. Unfortunately, none of these is a substitute for a glossary:
- Customer-facing Help Documentation – A project glossary can sometimes seed customer-facing language that ends up being used to train and support customers. But the intended audience for a glossary is the project design/implementation team and the stakeholders, not the end-user.
- A Data Dictionary – This type of document contains information about what is included in a database. Usually only database administrators interact with the data dictionary.
- Product Requirement Document (PRD) – The purpose of this document is to explain what the system should do through use cases and business rules. If the project has a PRD, it can be useful to reference it while compiling the list for the project glossary.
Why You Need a Baseline Vocabulary
The sooner a project team shares a common language to refer to their work, the quicker the individuals on the project will begin to gel as a team. When the team begins to share a common vocabulary, productivity takes off:
- Miscommunication is diminished.
- Versions of requirements documents are more consistent.
- Project stakeholders and the implementation team “speak the same language.”
- Business and technical requirements are easily explained and clarified when needed.
- Project team members learn quickly about new business areas or market segments.
- The implementation and design teams have an easier time making architectural decisions together.
Without a baseline vocabulary, the chances of making costly mistakes increase greatly.
How to Create a Project Glossary
What to Include
A basic project glossary should include the terms used in the project and their definitions specific to the project domain. That’s it!
An advanced project glossary can include any of the following:
- Regional variations and/or aliases for terms
- Common metaphors used to describe concepts
- Paradigm(s) that helps explain the solution or approach
- The context for overloaded terms (i.e., terms that are used interchangeably)
- Whether each definition has been approved or is still in an un-vetted state
The creation of a glossary should begin at the start of a project. A Business Analyst is usually responsible for creating one. However, if the project doesn’t have a BA, then the delivery lead or technical lead is the next logical member to create one.
Where to Begin
Start by plucking terms from any internal vision and scope documents. I’m referring to very early-stage thinking. These are artifacts that describe what a company has in mind to build and how they envision getting the work done. Other artifacts to examine include:
- Presentations, proof of concepts, and white papers
- Personas, user journey maps, and product roadmaps
- UI / UX designs
- System architecture diagrams, Entity Relationship Diagrams (ERD), and data dictionaries
- Project discussion forums such as Slack, Teams, Basecamp, etc.
Start simple by building a spreadsheet of terms and definitions that can eventually be shared out to the team.
Have a Discussion
Make sure the definitions are vetted by the team and approved by the stakeholder(s). This can be accomplished directly by geting everyone together in person or via video conference to hash out the definitions. With teams larger than five, I’ve found it can be most productive to create discussion threads in company forums to give everyone a chance to add their comments.
A project glossary needn’t be exhaustive to be useful to the project team. However, it needs to be kept current like any important project document. On one of my project teams, we add at least one term a week to the list even though the project has been in active development for six months.
Of all the essential documentation created to ensure a successful product delivery, the project glossary is one of the easiest to make. The benefits of having one can be felt immediately by promoting the consistent use of terminology amongst the project team.