Summer Internship Development: Improving the release notes webpage

Posted by Juris Majors on August 30, 2019

Motivation

During our summer internship in Tilburg, we worked on improving the current release notes website and the process of distributing release notes information to customers. Currently, release notes for each quarter are manually formatted, translated to PDF’s and then distributed to the customers. Our goal was to improve the website so that process would become less cumbersome.

Furthermore, the quarterly release notes are available only for a fraction of all 13 TOPdesk languages. Partially this is because the notes have always been manually translated and that takes a lot of time. Therefore, we experimented with different services and translator models to see if automatic translations are viable.

After the bootcamp, we spent the remaining 6 weeks of the internship on developing these functionalities.

Enough blabbering… how did we do all of it in one summer?

Quarterly filtering (Virtual Appliance & Classic)

In order for the release notes website to fully replace the old release notes, we decided to implement a filter which allows to filter release notes according to releases. For instance, we wanted to be able to show all the release notes belonging to a single release for on-premises TOPdesk versions. Furthermore, it also allows to see all the release notes between multiple versions. This allows clients to see the relevant release notes for the upgrades that they are considering.

The definitions of releases are hard-coded in a JSON. We could improve it by syncing with an official TOPdesk repository. However, it was out of scope for the summer internship.

Unread notes for SaaS

The SaaS version of TOPdesk does not have a clear definition of a release. However, it can have frequent releases. So, we thought that seeing unread release notes would be a nice addition to the SaaS page. 

To determine which release notes are unread, we simply store a cookie with the number of release notes last seen on the webpage. If that number is smaller than the number of notes listed currently, then group the latest notes in the unread box. The difference between the last seen amount and current is the number of release notes in the unread box.

Clearly, this is not a perfect solution, since it assumes that release notes only increase in amount. However, we only have to store the number of release notes, which is not user sensitive data. This could be improved by a more sophisticated cookie tracking approach. However, that was out of scope for this summer. 

Automatic translations

The release notes are manually translated, which takes a lot of time. We wanted to see if we could improve that. Therefore, we looked in to automating translations. After looking into the different viable options we narrowed it down to the following:

  • Google Translate
  • Microsoft Translator
  • DeepL

TOPdesk supports a lot of languages. Therefore, we decided that DeepL would not be a viable option, as it doesn’t support all of the languages that TOPdesk uses. When deciding between Microsoft and Google, we opted for Microsoft for multiple reasons: simple implementation with their API and other functionality, like training your custom translator.

Towards the end of the internship we started to feed data to Microsoft for German, French and Dutch models. To evaluate and compare these translators we carried out internal surveys.

Editing translations

We all know that automated translations can be disappointing. For instance translating ‘operators’ to ‘behandel aars’ instead of ‘behandelaars’. Clearly, such translations do not meet TOPdesk excellence standards.

However, sometimes an average automatic translation is better than no translation at all. When displayed on the user facing website, there is a warning:

Informing users that translations are imperfect isn’t an excuse to keep them that way. Therefore, we added functionality to manually edit and improve the automatic translations.

In the review page when selecting a language other than English, buttons for editing translations magically appear. To reduce clutter there is a filter for translated and automatically translated release notes. Very useful if one wishes to go on a translation editing spree.

Check out this example of editing a translation:

After clicking “Edit translation” options to “Cancel changes” or “Save translation” appear. If the user decides to save it, after a refresh it will be considered a manual translation. (YES, the HTML formatting stays while translating! No need to know any HTML!)

Checking the checkbox “Show English version” shows the English version appear, above the field where editing happens. It is useful when the translator needs a reference.

Closing remarks

After two months of programming, planning, designing, and some messing around, we are very satisfied with our final product. We are very grateful to Team Lynx, translators and everyone who filled in our surveys, came to our demos or showed interest in our work. Hope you enjoyed following our process and project.

Koen Degeling, Juris Majors and Gabriele Barteskaite

About the author: Juris Majors

More Posts