Build a Project Glossary in Confluence
A project glossary makes sure everyone means the same thing by the same word. Add new terms to a shared Confluence glossary page, with a plain meaning for each, in A to Z order.
Step by step
Why a glossary
- Project glossary. When a team uses one word in 2 ways, requirements go wrong. A project glossary fixes this. It is one shared page that lists every word the project uses and what each one means.
- Term and meaning. The glossary page has a table with 2 columns: the term, and what it means in plain words. The terms are in A to Z order, so people find them fast.
Add a term
- Edit. Click Edit to open the page in the editor.
- New row. Click in the last row of the table, then press Ctrl+Alt+Down arrow (Cmd+Option+Down arrow on a Mac). Confluence adds an empty row below the one you clicked in.
- The term. In the first cell of the new row, type the term the way the team says it: Shipping email.
- The meaning. In the cell next to it, write the meaning in one plain sentence: The email a shopper gets when an order leaves the warehouse. Write it so a new person on the team understands it on day 1.
- One more. Press Ctrl+Alt+Down arrow (Cmd+Option+Down arrow on a Mac) again to add one more row. Type Wish list. It comes after Shipping email, so the A to Z order stays right. Then add its meaning: Items a shopper saves to buy later. Say what it is, not how it is built.
Share it
- Update. Click Update to save the page, so everyone who can open it sees the new terms.
- Shared terms. Both new terms are now in the glossary. Link to this page from your requirements and user stories, so every reader checks the same meaning.
Recap
- One word, one meaning. In short: one shared page, one row per term, a plain meaning for each, in A to Z order. Add a word the first time the team argues about what it means.
Common mistakes
- Adding the new row in the wrong place. Ctrl+Alt+Down arrow (Cmd+Option+Down arrow on a Mac) adds the row below the one you clicked in. Click in the row that comes just before the new term in A to Z order, so the list stays sorted.
- Saying how it is built, not what it is. A meaning full of system names only helps developers. Write what the thing is in words a new team member understands, like Items a shopper saves to buy later.
- Leaving the editor without clicking Update. Other people don't see your new terms until you click Update. Click it when you finish each round of changes.
- Two words for the same thing. If the team says both Wish list and Saved items, pick one term and mention the other in its meaning. Then nobody thinks they are 2 different features.
When a business analyst uses this
In a requirements workshop, the business uses Order to mean both the cart and the paid purchase. The business analyst adds Cart and Order as separate glossary terms with one plain meaning each, then links the glossary page from the requirements and user stories before sign-off, so every reader works from the same meaning.
Questions people ask
What is a project glossary?
It is a shared list of the words a project uses, each with one agreed meaning. It stops people using the same word in different ways, which leads to wrong requirements.
How do I add a row to a table in Confluence?
While editing the page, click in a row and press Ctrl+Alt+Down arrow (Cmd+Option+Down arrow on a Mac). Confluence adds an empty row below the one you clicked in.
When should a term be added to the project glossary?
Add a word the first time the team argues about what it means. Write its meaning in one plain sentence that a new team member understands.
