This is a guest blog by Charles Hall from OpenBet, a specialist software company that provides gambling and gaming solutions.
In part 1 of this article we set the scene and created the basic elements for capturing glossary terms. This included the use of live templates and scaffolding fields to ensure that data is captured in a structured fashion and that the whole system is easily maintainable. We also saw how a special link is needed to reference a page template as a “live” template. With that link in place a colleague with expert domain knowledge began populating the glossary with specific terms. I set about devising structures to help users find information easily within the glossary. Fortunately Confluence has some great standard capabilities for this. With the aid of a few selected plugins, some additional mechanisms are easy to implement. Are these strictly necessary? Different approaches appeal to different users, so I’d personally prefer to offer a range of options and allow users to use whichever method suits them best. Analytics (either within Confluence or possibly GoogleAnalytics) will show over time which ones are being used and which aren’t.
So in this part of the article we’ll examine how we implemented the following mechanisms to help ensure the information recorded in the glossary can be retrieved effectively:
- Targeted search
- List of terms grouped alphabetically
- List by domain
- Knowledge base ratings
Helping the process of information discovery
First, we chose the Documentation theme for the glossary space so, a dedicated space search was already in place in the left hand navigation sidebar. However, this did not have the auto-suggest which would be useful for providing users with a speedy search. Fortunately Confluence allows you to control precisely what goes into the left hand navigation sidebar. I’ve found the most flexible way to do this is to have a page called “navigation” to hold all the elements you want to show, then reference this in ‘Space Admin – Configure Theme’ with the aid of the page include macro: {include:navigation} Then in the navigation page we simply need to include the {livesearch} macro, which does offer the auto-suggest behaviour:
The other content within the navigation page includes an A to Z list of links, allowing the user to jump to a page where terms have been grouped alphabetically. To ensure these links are presented nicely, we’ve encapsulated each of them within a div macro (from Adaptavist’s free Content Formatting plugin) which references a CSS style defined with the aid of the style macro from the same plugin. The entire contents of the navigation page is shown in the following code snippet.
Page: Navigation
Having introduced the A to Z pages, we should probably describe them in a little more detail. It would become very tiresome to have to maintain these pages manually. Fortunately we don’t have to 🙂 . It’s time to introduce one of the most useful plugins available for Confluence. Reporting from Customware offers a number of macros which can analyse Confluence objects such as users, pages, comments and attachments.In addition, it dovetails perfectly with the Scaffolding macros so that the analysis can be performed at the level of specific fields within a page.
So to generate a summary list of all the terms beginning with a specific letter, we’ll use the report-block macro as the container to output the title and definition text for each term. The terms will be identified using the content-reporter macro. To pinpoint the terms we’re interested in, we’ll set parameters so that Reporting knows to look for pages only (i.e. not comments or blogs), with the label “glossary_definition”, which can be found under the Definitions page in the glossary space. Furthermore, the text-filter macro allows us to be very specific and say that the first character of the page title must be either “a” or “A”, otherwise ignore that page. It’s up to us to choose what attributes of the term we’re interested in including in the list. In our case, we included the term being defined, with a link on it, plus its definition text.
Page: A
Here’s an example of such a summary page:
In part 1 of the article we alluded to a way of categorizing a glossary term according to a specific domain (see the Domain drop-down list-data element in the Definitions page template and also the Domain Links included page). Similarly to how we pinpointed all the glossary terms beginning with A, B, etc, we can use Reporting to collate the terms into lists, one for each of the allowed domain options, based on the recorded domain value. Note the regular expression in the text-filter macro which achieves this.
Page: Summary by domain (architecture)
These summary pages are also a target for links built into the definitions page template. In part 1 you may remember that we defined a page called Domain Links which was included into the page template. The coding in here ensured that whatever domain the user chose for a definition would be transformed into a link. The target of that link would be one of these summary pages.
The final main navigation option we decided to offer was a summary on the space home page, listing those glossary entries which have been highly rated using the Knowledge Base survey macro. This is easily achieved using the Top Ranked Articles macro (also from the Content Survey & Reporting plugin).
Here’s how this looks when the page is viewed normally ({kbtoparticles:10}):
To be continued…
We’ve now created four navigation mechanisms to facilitate information discovery. In the final part of this series, we’ll put into practice what we’ve preached about maintainability and share with you how the glossary has been tuned to deliver some unexpected productivity benefits.
New to Confluence?
Want to get started building your own company glossary? It’s easy to get started with Confluence with our FREE 30-day trials.