How to make a glossary in Confluence

[Melanie Albrecht]

I have a glossary with 150 terms, with more to come. My current setup is OK, but I'm looking around to see if there's a better way. What do you think of my options? Anything better to suggest?

Current situation: one enormous table

In my enormous table, each term has a definition plus other information. The Definition cell includes an anchor, which lets me make each link in the See Also column jump straight to the row that defines the related term.

Limitations of the huge single table:

• The page is enormous, and will only get bigger.
• I'd like to be able to show these definitions in other pages, but I don't have the Multi-Excerpt plugin.

Other possibilities

• Create lots of little pages (one per definition). Display them using Page Properties macro. Use a single Excerpt on each little page to let me drop definitions onto other pages.
  
  I've baked my own index page to test this, and it works fine. However, I cannot link to a particular row in the table generated by the PP macro, which breaks my See Also links.
  
  
• Buy the Glossary plugin. The reviews of this plugin are not particularly favourable.
  
  
• Keep using my massive table, and buy the Multi Excerpt plugin to allow me to drop definitions into other pages.
  How scalable is this plugin?
  Could it cope with 200+ excerpts on a single page?

Example of my one enormous four-column table:

Term	Definition	See also	Organisation
ACI	Cisco Application Centric Infrastructure (ACI) is a data-centre focused technology platform from Cisco that allows the network fabric to be managed as a whole rather than each individual device. More: Cisco: Application Centric Infrastructure (ACI)  More: Techtarget: How Cisco's Application Centric Infrastructure differs from SDN	Related: DevOps SDN	Cisco
AS	Within the Internet, an autonomous system (AS) is a collection of connected Internet Protocol (IP) routing prefixes  under the control of one or more network operators on behalf of a single administrative entity or domain that presents a common, clearly defined routing policy to the Internet. More: Wikipedia: Autonomous system (Internet)	Related: BGP BGPRIB EBGP	General
ASR	Cisco has a range of aggregation services routers (ASRs). These are typically used at the internet edge for enterprise networks and service providers.	Related: ISR CSR	Cisco
Azure	Microsoft Azure is a cloud computing platform for building, deploying and managing applications and services through a global network of Microsoft-managed data centres.	Related: Azure AD	Third Party

Thanks,

Melanie

[James Wilkins · Accepted solution]

I realise I'm a little late to this discussion but I wanted to share a work-in-progress that I created after absorbing all the ideas and feedback from this thread—as well as those created by @Patrick O_Connell—with the aim of creating the ultimate glossary for my company's Confluence instance.

Acceptance criteria:

• Must be able to be maintained by the community
• Must be easily-accessible and easy to navigate

Desired features:

• Ability to search for a glossary entry ✔️
• Ability to create a new entry from a template ✔️
• Ability to view glossary entries categorised alphabetically ✔️
• Ability to view excerpts of each entry on the index ✔️
• Ability to view a glossary entry's full page on-hover from the index ❌

      ✔️ Achieved; ❌ Not achieved

----

Here's what you'll need to do:

1. Create a separate Space for your glossary
   1. This way, you don't get any clashes when naming pages.
2. Space Settings > Content Tools > Templates: Create a User-Created Template for your glossary entries
   1. Name the template "Glossary entry" or similar
   2. Add sections for: Short description, Full description, Abbreviation(s)
      1. Up to you which sections you include in your glossary entry pages
   3. Add an Excerpt macro to the Short description section
   4. Use the Placeholder Text macro to inform users what to include in each section
   5. Make sure to label the template with a "glossary" label or similar
      1. New pages using this template will inherit this label
   6. From Space Settings > Content Tools > Templates, click "Promote".
      1. This means the template will show at the top when creating a new page on your glossary Space (not entirely necessary, as you'll create a macro which will do this part automatically for the user)
3. Add a Livesearch macro to the Overview page
   1. Restrict to label(s) = "glossary" (or whatever your parent label is, set during "Create a User-Created Template")
   2. Content type to include in search = "page"
   3. Additional information = "page excerpt"
4. Add a Create from Template macro to the Overview page
   1. Button text = "Create new entry"
   2. Template name = The name of the template you set during "Create a User-Created Template"
   3. Title of page to be created = "<Insert full, unabbreviated name of glossary term here>"
5. List out the alphabet ("Aa", "Bb", "Cc", etc.) as separate headings on your Overview page
   1. Consider using a two-column format so the page doesn't get too long
6. Starting with the "Aa" heading, add a Content by Label macro
   1. Untick all boxes and remove values from every field except for:
      1. Sort by = "title"
      2. Excerpt Display = "simple"
   2. Populate the Label field with a label corresponding to alphabetical sorting:
      1. E.g. "glossary_sort-a"
7. Copy your Content by Label macro and paste it under every letter heading, creating a new label for each letter as you go in the Label field
   1. Each Content by Label macro should only have one label assigned to it based on the letter heading it represents
8. Time to test it out!
   1. Activate your Create from Template macro which should take you straight to a new page editor.
      1. Write something in the Excerpt box
      2. Publish page
      3. Check that this new page has the "glossary" label assigned to it
      4. Assign the alphabetical label (e.g. "glossary_sort-a") to the page manually
   2. Go back to your Overview page and:
      1. Check that the entry is under the correct letter heading
      2. Check that the Excerpt is displaying correctly
9. Done! Make sure it looks presentable and starting populating your new glossary with all of that confusing vocabulary!

I'd be grateful for any feedback on this method of creating a glossary. Assuming I've understood everyone correctly, this seems to be the most ideal version of a glossary that you can easily make in Confluence.

If anyone knows how to create on-hover functionality on the index page OR a way that I can make abbreviations, for example, visible on the index without including them in the glossary entry's page title, please let me know!

Of course, feel free to bat any questions my way and I'll do my best to answer!

[rhonda mcdonough]

James, this was great. took me about 2 hours to get it all set up and documented for others to start adding terms to our glossary space. another really nice for us feature of this is you can add any page to our glossary space just by adding 2 tags to the page. I set it up so the search works on label named `glossary` and the listing of the glossary entries are by labels that are 4 of the same character. so for our POC term, that is an existing page and to get it to show up i just had to add the labels `glossary` and `pppp`.

thanks for your post!

[TomC · Accepted solution]

Hi Melanie,

We have a glossary of over 6000 terms and growing, each on a separate page (one per definition). It is open to our company of almost 8000 employees. As a side note, it also comes built-in with a prominent search field on the landing page and the as-you-type hits are just from that space.  And an option we like (not required): a built-in Index (entries are sorted and can be paged through A, B, C, pages which display hyperlinked, alphabetized titles of entries which some find useful to be able to scan what's in there - i.e. they may not think of searching but like to discover by browsing).   

It was done under contract with a noted Atlassian Expert and I understand will soon be on the Marketplace.  If curious to hear more (please understand, I'm an Atlassian customer and don't work for the third-party company either; willing to discuss/screenshare what our solution looks like), feel free to contact me at tomcrespi@gmail.com 

We have had many employees contribute to our glossary by the way - it's by far our most contributed-to Confluence space out of the few hundred we have.

Tom

[Melanie Albrecht]

Thanks very much, Tom. I will indeed contact you to find out more.

[Felix Kipper]

I also would like to see more, so I will contact you. 

[Jen]

Tom,

Your workaround to create a Company Glossary makes the most sense to us too.  Was there a particular type of Space you used that worked best?

Thanks,

Jen

[Alex O'Donnell]

Looking at Tom's "page per definition" glossary, and taking that for inspiration, I am thinking

1. Definition per page dictionary/encyclopaedia.
2. Make sure each page has an excerpt.
3. Label/tag each definition page with "glossary"
4. Create another page which is an index using "content by label" an automatic table of label where the title and excerpt are displayed (https://confluence.atlassian.com/confcloud/use-labels-to-organize-your-content-724764874.html)
   1. 
      
   2. 
   3. 
5. Once my index page gets too large, split it for alphabetical groups.

I created a template for "glossary entry".

The template starts with an excerpt macro, filled with "placeholder text" saying "enter brief for glossary here"

Next template has space for a full defintion

Template has label "glossary" set, and will auto label any page created by said macro.

Glossary pages can be created anywhere within the space, so you can put definitions where it makes sense, and they still get added to the glossary page!

Does anyone see any peril or merits to this?

[Melanie Albrecht]

I ended up doing pretty much the same thing that you are describing.

It worked OK. However, it was pretty fiddly to maintain.

This would be OK if you plan to be the one to own the glossary, and be responsible for updating it.

It's not good if you expect a wider group of people to maintain it.

[Uma Khoosal]

Hi Melanie

How long did this take you to setup and complete?

[Melanie Albrecht]

Hi Uma

I don't recall exactly, because I set it up in 2016.

I would estimate that I took a week in total. Probably 3 days to trial various config options, and then a couple of days to input my data.

But as I said above, I would not recommend this for a glossary where you expect a wide range of people to keep the definitions up-to-date. It's too fiddly.

Regards,
Melanie

[Uma Khoosal]

Hi melanie

thank you for replying. i would be in charge of keeping this up to date. my users will either agree or if they disagree they would make a comment. i would make the changes and maintain it

[Melanie Albrecht]

Sounds reasonable, then.

[Melanie Albrecht]

Let me know if I can help by exporting some of my pages so you can see what I did.

[Uma Khoosal]

Yes please. that will be amazing. Thank you. do you have my email address?

[Melanie Albrecht]

I can't see your email address from your profile. Put it in here in a reply, I'll copy it, then you can delete your reply so your address isn't too public :-)

[Uma Khoosal]

thank you

[Jen]

Hey all rejoining thread. 

We have a leadership/content author team of about 40 people and an organization of 300 and growing, with me being the only active super user.  

Each department is responsible to keep their team space and all department content updated; conducting an annual audit each year.  

The glossary space was a bit of a challenge to assign ownership, as many departments use the same terms.  We've been hesitant to allow everyone access to add content (pages) as we want to ensure the integrity of the definition is in tact with as little oversight as possible.

I found the Labeling to be a challenge.  I'm 100% sure I understand your method @Melanie Albrecht  & @Alex O_Donnell 

I don't know how to separate the page index to a specific alphabetical group.  We'd love to use this concept on other Spaces to create a Rolodex in the page menu.

Appreciate your support!

[Patrick O_Connell]

Hi Jen,

Could you not use multiple labels, à la :

glossary-a_to_i

glossary-j_to_o

glossary-p_to_z

...so each term-specific page would us one of those three, as appropriate?

Then you would have:

    Summary page for A to I - Content by Label macro picks up only glossary-a_to_i tag

    Summary page for I to O - Content by Label macro picks up only glossary-j_to_o tag

    Summary page for A to I - Content by Label macro picks up only glossary-p_to_z tag

And maybe one parent/introductory page with links to these three.

Does that make sense?

Cheers,
Pat O'Connell
Technical Writer
MindGeek Montreal

[Jen]

I love this idea - thanks Pat!

[James Wilkins]

I realise I'm a little late to this discussion but I wanted to share a work-in-progress that I created after absorbing all the ideas and feedback from this thread—as well as those created by @Patrick O_Connell—with the aim of creating the ultimate glossary for my company's Confluence instance.

Acceptance criteria:

• Must be able to be maintained by the community
• Must be easily-accessible and easy to navigate

Desired features:

• Ability to search for a glossary entry ✔️
• Ability to create a new entry from a template ✔️
• Ability to view glossary entries categorised alphabetically ✔️
• Ability to view excerpts of each entry on the index ✔️
• Ability to view a glossary entry's full page on-hover from the index ❌

      ✔️ Achieved; ❌ Not achieved

----

Here's what you'll need to do:

1. Create a separate 'Space' for your glossary
   1. This way, you don't get any clashes when naming pages.
2. Space Settings > Content Tools > Templates: Create a 'User-Created Template' for your glossary entries
   1. Name the template "Glossary entry" or similar
   2. Add sections for: Short description, Full description, Abbreviation(s)
      1. Up to you which sections you include in your glossary entry pages
   3. Add an 'Excerpt' macro to the Short description section
   4. Use the 'Placeholder Text' macro to inform users what to include in each section
   5. Make sure to label the template with a "glossary" label or similar
      1. New pages using this template will inherit this label
   6. From Space Settings > Content Tools > Templates, click "Promote".
      1. This means the template will show at the top when creating a new page on your glossary Space (not entirely necessary, as you'll create a macro which will do this part automatically for the user)
3. Add a 'Livesearch' macro to the Overview page
   1. Restrict to label(s) = "glossary" (or whatever your parent label is, set during "Create a User-Created Template")
   2. Content type to include in search = "page"
   3. Additional information = "page excerpt"
4. Add a 'Create from Template' macro to the Overview page
   1. Button text = "Create new entry"
   2. Template name = The name of the template you set during "Create a User-Created Template"
   3. Title of page to be created = "<Insert full, unabbreviated name of glossary term here>"
5. List out the alphabet ("Aa", "Bb", "Cc", etc.) as separate headings on your Overview page
   1. Consider using a two-column format so the page doesn't get too long
6. Starting with the "Aa" heading, add a 'Content by Label' macro
   1. Untick all boxes and remove values from every field except for:
      1. Sort by = "title"
      2. Excerpt Display = "simple"
   2. Populate the Label field with a label corresponding to alphabetical sorting:
      1. E.g. "glossary_sort-a"
7. Copy your 'Content by Label' macro and paste it under every letter heading, creating a new label for each letter as you go in the Label field
   1. Each 'Content by Label' macro should only have one label assigned to it based on the letter heading it represents
8. Time to test it out!
   1. Activate your 'Create from Template' macro which should take you straight to a new page editor.
      1. Write something in the Excerpt box
      2. Publish page
      3. Check that this new page has the "glossary" label assigned to it
      4. Assign the alphabetical label (e.g. "glossary_sort-a") to the page manually
   2. Go back to your Overview page and:
      1. Check that the entry is under the correct letter heading
      2. Check that the Excerpt is displaying correctly
9. Done! Make sure it looks presentable and starting populating your new glossary with all of that confusing vocabulary!

I'd be grateful for any feedback on this method of creating a glossary. Assuming I've understood everyone correctly, this seems to be the most ideal version of a glossary that you can easily make in Confluence.

If anyone knows how to create on-hover functionality on the index page OR a way that I can make abbreviations, for example, visible on the index without including them in the glossary entry's page title, please let me know!

Of course, feel free to bat any questions my way and I'll do my best to answer!

[Patrick O_Connell]

This is great if you your employer will actually consent to having a separate space for a glossary, and if you're a space admin for it. For example, the latter is something possible for me, having asked and had it happen. The former is not, having asked and had it not happen. :-)

Under those conditions, this is very well-documented, and doubtless useful to many.


Pat O'Connell
Technical Writer
MindGeek Montreal

[Josef Popelka]

Hi James

can you please share some print screens what should be final outlook? 

Thanks in advance Josef

[Daniel Orgonik]

I would also appreciate the screenshots related to particular steps. Thank you 

[James Wilkins]

Here are some crude screenshots of both the main Glossary page and the individual Entry page (in Edit mode), as well as the macro windows so you have an idea of how it might look and how it all works.

I hope this helps, apologies for the lack of detail.

[Daniel Orgonik]

Hi James,

thanks a lot for your reply and willingness to help.

In step nb 2 you say "Add sections for: Short description, Full description, Abbreviation(s)" - could you please show how you did that? I mean add section.

Many thanks

[James Wilkins]

No problem Daniel,

If you take a look at KCYC2.jpg, you'll see 3 sections under the "Point of Interest" heading: Short description, Abbreviation(s), Full description.

Short description would hold the Excerpt macro, a brief explanation of the glossary entry.
Abbreviation(s) would hold common names, acronyms or abbreviations for the glossary entry.
Full description would hold the detailed explanation of the glossary entry.

These are simply headings that dictate the information you'd like to see if your glossary entries. These could be customised to your needs and don't have to follow what I've outlined--much the same as everything I've outlined in the guide; it's simply a foundation for you to build the perfect Glossary for your Confluence space.

So when it says "add section", it simply means to add a heading within the page.

[Daniel Orgonik]

Many thanks, James

[Deleted user]

@James Wilkins : This is AWESOME. I am unable to reach the template page like a regular page, though, and apply a label to it. How did you accomplish that?

UPDATE: I now see that in the new design, you add labels while editing. The "Add labels" option can be found in the kebab menu ( . . . ) in the upper right corner. 

[Mike Raath]

@James Wilkins thank you very much for this, I followed your steps to the letter (well just about) and we now have a very usable glossary that any employee can contribute to.

[Bernd Schneider]

@James Wilkins Hi, that really looks very sophisticated. But we would have an additional requirement: having a term in the text and show the short description when hovering over that with the mouse.
Does anybody else has this requirement and maybe a solution for it?
There is a hover-over/tooltip function for links in Confluence, but there you have to insert the text where you are. There seems to be no possibility to fetch the text from a separate source, like a table/DB/other page.

Thanks in advance!
Bernd

[Sergey Rodin]

@James Wilkins Hi, thank you for this detailed instruction, I just set the whole thing up. I have two follow-up questions:

1. How do you deal with terms have many definitions? For example, the term "Order" in my company has two or three different definitions, and I could list them in both "Short description" and "Long description" sections using a numbered list, unless there's a better solution.
2. In the page tree of the Glossary space, did you add any top-level organizer pages for each letter, such as "Aa", "Bb", "Cc", and so on? Or did you have all the pages with terms arranged alphabetically without any extra headings?

Thanks!

[Patrick O_Connell]

@Sergey Rodin, re: #1, what about enumerating them, in the headings "Order (1)," "Order (2)," etc? Would that work?

Re: #2, I did create letter headings, for my glossary. Had a big of fun creating them, in Photoshop. This shows a couple of them:

Cheers,
Pat O'Connell
Technical Writer
MindGeek Montreal

[Andy Folland]

Hello folks,

First of all - a huge thumbs up to James Wilkins for that massive contribution - that is supremely generous of you.

Secondly, a few folks here have enquired about some kind of mouseover type feature. Much as I hate being sent over to the marketplace to look for stuff, FYI the VECTORS Glossary app has a highlight function that might do something pretty close to what you are looking for:
https://marketplace.atlassian.com/apps/1211800/glossary-for-confluence?hosting=cloud&tab=overview

However, please also note that I am here currently looking for an alternative solution because this app has failed to work in one of our spaces and we are currently waiting on an update on a logged ticket with them. 

[Rosalind Loo]

Thanks this was really useful.

Have created a glossary based on your guidance. I'm thinking of adding a few more things to it:

1) Tagging. I was wondering how do you go about TAGGING glossary terms? There may be a group of terms that related to topic A, or topic B- has anyone implemented a labelling system? 

2) Showing abbreviations in the main glossary page. How do you recommend brining that into the main page?

Thanks in advance.

[Patrick O_Connell]

Hello @Rosalind Loo

1) I'm not quite sure what you mean by tagging. The only tagging-like mechanism native to Confluence (i.e., without plug-ins)  is labels, so if I'm understanding you correctly, that's what you would use.

2) What do you mean by abbreviations? The method I lay out in:

https://community.atlassian.com/t5/Confluence-discussions/A-Confluence-glossary-where-you-can-put-letter-headings/td-p/1203774

...includes having a shortened version of the full definition show up in the glossary root page. I'm not sure if that's what you mean, though.

Best,
Pat O'Connell
Technical Writer in Residence (my own, that is!)
MindGeek Montreal

[Rosalind Loo]

Hello @Patrick O_Connell 

1) I'm looking for a way to classify the glossary terms, whilst appearing in the alphabetical list. In confluence, the "Status" symbol is best - ie colour + text. For example the glassary term may be related to "sales", or "support". 

2) Abbreviation-  I've followed your method and am using the extract macro which is great! However for example a glossary term "Subscriber", might also be known as "Subs" as an abbreviation. Ideally I'd have 3-4 sections in the glossary list (Glossary term, extract of explanation, abbreviations if available, classification code ie #1). I guess a simple way to solve this would be to include it in the glossary term title itself "Subscriber, Subs, Other abbreviations..."  

Thanks! 

[Deleted user]

@Rosalind Loo : Hey, Rosalind, I don't know if this is what you're looking for, but I noticed that there are custom status blocks you can insert on pages now. I wonder if they can be used in the way you mention?

[Patrick O_Connell]

Hello,

I meant to cross-link this the other day, when I created this new discussion, but here's something that builds on ideas from 3 or 4 people in the above, including myself:

https://community.atlassian.com/t5/Confluence-discussions/A-Confluence-glossary-where-you-can-put-letter-headings/td-p/1203774

I think this is close to the limit of how fancy-schmancy you can get with a glossary in Confuence, sans macros, but hey, feel free to argue otherwise!

And no, you can't have my letter-heading graphics! :)

Pat O'Connell
Technical Writer
MindGeek / Montreal

[Patrick O_Connell]

Good day.

I'm still working on my updated glossary, and I had Eureka! moment I describe in a discussion I started, here:

https://community.atlassian.com/t5/Confluence-discussions/Importing-a-Word-doc-to-create-multiple-pages-A-light-bulb/m-p/1200460#M6076

I have also figured out a really cool way to have letter headings in the term index, building on @Alex O'Donnell 's method, up there. More on that, later!

All my best,
Pat O'Connell
Technical Writer
MindGeek Montreal

[Patrick O_Connell]

Hey folks,

@Alex O'Donnell was asking, now way up there, people's thoughts re: perils and merits of the method they described.

I want to reformat a glossary that's currently one very long page, was intrigued by the method, and did a little trial in my personal space.

Good: 

1. Very easy to integrate new terms / new pages: You just have to put the right label(s), and the Content by Label macro automagically picks up what's new.
2. You don't have everything on one crazy-long page.

Not so great:

1. What's described for Good, above, is better if it's one person owning and managing the glossary.
2. I find it frustrating to not have more control over format of the page-summary entries. In my one-very-long-page version, at least I was able to designate each term title as a Heading 3.
3. A page for every single term = a lot of individual pages.

All the best,
Pat O'Connell
Technical Writer
MindGeek Montreal