The Tip of the Month, brought to you by Atlassian University, is a monthly series to help master Atlassian tools. Products are more fun to use when you know all the tricks.
This is a guest blog by Charles Hall from OpenBet, a specialist software company that provides gambling and gaming solutions.
Maintenance and Re-use
With the templates and navigation schemes we set-up in part 1 and part 2 of this article, and thanks to some initial seeding of content, the glossary space is established and open to everyone in the company. But this isn’t the end of the story. Different users will come along with new feedback, and situations arise that weren’t foreseen. The good news is that the “live” template approach we took, means we’re in good shape to make changes easily. Let’s see how the glossary developed at OpenBet during its first few months of usage.
Responding to user feedback: Updating the look & feel
Following the introduction of the glossary we monitored it carefully to see how people were interacting with it. While we started to see some definitions being edited, and comments used for discussions, the feedback questions posed with the aid of the knowledge base survey plugin elicited very little response. Hence we decided to change the feedback mechanism and offer a simpler rating system instead. For this we used the Rate plugin by Adaptavist. As we used a “live” template, applying this change to the existing definition pages was simply a case of amending the template: Before/After
The results of this change are a more compact and colorful feedback section:
The change has proved a positive one, as we’re now seeing people starting to use the rating system. Putting the companion {rate-search} macro on the home page of the glossary space also offers users an additional navigation mechanism, and encourages users to consider rating any definitions they view. We implemented another visual change shortly after the launch of the glossary, at the request of a user who found the presentation difficult to read. In the original template we presented the definition text inside a panel, which used a color from our corporate color palette as the background. We’d also chosen to show the definition in italics. We accepted the user feedback and revised the presentation as you can see below:
The new presentation is clearer, while still respects the corporate color palette. This change was applied easily by making a small modification to the definition of the panel in the page template (for the border thickness & background color), and the italics removed by editing one of the jQuery statements in the “panel formatting” page described in part 1. Arguably, it would be nice to make all the changes in one place, but for now our approach has been to make use of the available parameters offered by page elements such as panels and resort to jQuery tweaks only for those things we can’t achieve through the normal editing options.
The ease with which these changes were implemented illustrates the benefits of the live template mechanism for maintaining a consistent look and feel across quite a large space.
Single-sourcing: one glossary to rule them all
Recently we’ve had a team start-up to work on a new customer project. They were keen to use the glossary to establish common ground with the customer. Rather than create a separate customer specific glossary, which would have lead to fragmentation of information, we opted to use labels to tag relevant terms with the customer’s name. With the aid of the Reporting plug-in once again, its a case of filtering on that label to obtain a complete list of relevant terms which can be exported to PDF form and shared with the customer easily.
With the content-reporter macro, filtering by label is one of the standard parameters. The code sample below shows how we’re setting the scope to be just those pages with labels of “glossary_definition” and “projectkey”.
We realized that there was a need to separate customer specific text from the main definition, otherwise we risked sharing information between customers. This meant introducing a new rich text field into the template to capture such information: http://pastebin.com/RsXwRQXi
With this field in place the original “definition” field can be used solely for generic information. The production of the PDF form of the glossary can then incorporate just the generic definition text, leaving out anything that was customer specific. And so the A to Z pages were tailor made to be included into the PDF export, as they only contain the term and the generic definition. This solution worked well, as we’re finding that without prompting, authors and editors are using the customer specific field in the way we intended.
Using the glossary as a custom dictionary
Internally, we identified a way the glossary could be re-used to give a productivity benefit. The large number of definitions in the glossary shows the extent of specific terminology to our business, which most spell checking software is unaware of. What if we could package the glossary definitions into a form which could be used by MS Office, LibreOffice or even a browser spell check plugin as a custom dictionary?
It’s relatively simple to create a custom dictionary file for both MS Office and LibreOffice, but common to both is a list of terms representing valid words. To produce this in Confluence we used the Reporting plugin once again to analyze the glossary definition pages and filter them before compiling a simple list. The list needs to be well formed though, with one term per line and no breaks. We found that most spell checkers are not as smart as you might hope for, so the list needs to include the variations of the word that may occur, for example “Antepost bet” and “antepost bet”. It’s not possible to generate these variations automatically, so we decided to put another field into the template for this purpose. You’ll see we only present this if the page is being edited, as we feel its the authors responsibility to maintain this. The page is cleaner in this way for other users just viewing the definition.
The following code sample is for the page which will produce the complete list of terms. We used some jQuery coding here to eliminate empty lines, replace commas with line breaks, and then paragraph marks with line breaks. The jQuery code could be optimized, but is presented here for easier understanding: http://pastebin.com/Aw3qKkhm
It’s probably easiest to create the custom dictionary in MS Office or LibreOffice first with one entry. This will give you a file on your file system which you can then edit with a text editor and simply drop in the list of terms given by the listing above. If you use other systems with a spell checking facility, then the principles may well be the same. GoogleDocs is one notable exception however.
- How to add a custom dictionary in Word
- LibreOffice Writing Aids
- Google Drive – spell checking powered by the web
We’ve published the custom dictionary files on our intranet, with instructions explaining where they need to be installed for our users. It may also be possible for your company IT team to deploy it silently to all the PCs in your domain, and refresh it from time to time as the glossary grows. The end result is that the red squiggly lines applied by the spell checking tools now actually mean some action needs to be taken! Previously it was difficult to see genuine typo’s from the specialist words the dictionary didn’t understand, and too many false alarms are simply counter-productive.
Conclusion
We now have well over 700 terms within our glossary, with recent additions coming from the project teams within the business. It’s proving to be a valuable source of information for experienced team members but of course for people new to the industry we work in. We make a point of introducing every new starter to the company to this resource within a few days of their arrival, and we know from their feedback that its helping to propel them up the learning curve. Here’s some typical usage stats:
The graph of page views is gratifying, but understanding who is editing and adding to the glossary is an important measure. In our case, just under 10% of the entries have been created by someone outside the Documentation team. The rest of the company are also editing definitions, as a result of project work which uncovers new information people judge worthy of sharing. The added benefit here is that we will start to recognize who are the expert authorities for particular areas, and so there is an opportunity to make good use of the enterprise social network feature.
In terms of navigation, we can see that the summary pages by domain and the A to Z pages are being accessed frequently. It would be nice to understand how frequently the live seach box is being used. GoogleAnalytics should be capable of doing this, but we’ve only recently configured it to track this so it’s too early to draw any conclusions.
While improving knowledge transfer is a worthwhile endeavour, it’s often difficult to quantify the benefits. Can you really be sure that new team members are absorbing knowledge more effectively? And if you can, can you demonstrate this? All of us may well have faced this sort of question in years gone by when trying to justify investment in a corporate wiki project. Hopefully this series of articles has shown that just a handful of carefully chosen plugins can provide the additional flexibility needed to manage information more effectively. In our case, we can see that the effort has been rewarded by a significant amount of traffic and knowledge sharing, and delivered unexpected benefits such as the custom dictionary and even customer deliverables.
Share Feedback
If you found this blog series useful and want to provide additional or more specific feedback, Charles would love to hear it! Feel free to contact him at: https://answers.atlassian.com/
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.
If you found this helpful, please visit Atlassian University – interactive tutorials and videos with tons of tips just like this one.