Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Next challenges

Recent achievements

  • Global
  • Personal

Recognition

  • Give kudos
  • Received
  • Given

Leaderboard

  • Global

Trophy case

Kudos (beta program)

Kudos logo

You've been invited into the Kudos (beta program) private group. Chat with others in the program, or give feedback to Atlassian.

View group

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

How to make a glossary in Confluence

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:

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:

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:

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:

Third Party

 

Thanks,

Melanie

7 answers

1 accepted

2 votes
Answer accepted
TomC Community Leader Jun 13, 2016

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

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

Like Gregtrester likes this

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

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

Like Victor Castano likes this

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. GlossaryPage.png
    2. GlossaryPageContentByLabel1.png
    3. GlossaryPageContentByLabel2.png
  5. Once my index page gets too large, split it for alphabetical groups.

 

I created a template for "glossary entry".
GlossaryTemplate.png

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?

Like shashank padwal likes this

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.

Hi Melanie

How long did this take you to setup and complete?

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

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

Sounds reasonable, then.

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

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

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 :-)

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!

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

Like # people like this

I love this idea - thanks Pat!

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!

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!

Like James Wilkins likes this

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!

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

Hi James

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

Thanks in advance Josef

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

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.

KCYC1.jpgKCYC2.jpgKCYC3.jpgKCYC4.jpgKCYC5.jpg

Like # people like this

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

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.

Like Daniel Orgonik likes this

Many thanks, James

Like James Wilkins likes this

@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. 

Like James Wilkins likes this

@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.

Like James Wilkins likes this

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

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

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

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.

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

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! 

@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?

Suggest an answer

Log in or Sign up to answer
TAGS
Community showcase
Posted in Confluence

What do you think is the most *delightful* Confluence feature? Comment for a prize!

- Create your own custom emoji 🔥 - "Shake for Feedback" on mobile 📱 - An endless supply of GIFs via GIPHY 🤩 Is there anything quite as nice as a pleasant surprise? Comment below with what...

335 views 23 8
Join discussion

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you