Merge glossary template into terminology system template

Background

Coming from #379 (closed), and while working on v2 of the glossary template, we identified that there was likely going to be a lot of crossover between a potential new version of the glossary template and the current terminology system template.

With this in mind, and after discussing with @camerons1 and the template working groups (Team Macaw in particular), we contemplated that a possible way forward could be to merge the existing glossary template into the terminology system template.

The idea would be to take all the "good bits" from the glossary template and fit them into the current terminology one, providing a better experience for both template users and maintainers.

Benefits of doing this

  • From a GDP user experience point of view, having only one template to consult for glossary/terminology management reduces ambiguity when it comes to deciding which one to adopt. The guide document already includes an extensive comparison of both approaches (glossary vs terminology system) and how to decide which one you need in your project/org.
  • Going forward, the management and maintenance of this template within GDP becomes a lot more sustainable for GDP members. It's a more unified approach to glossary/terminology management.
  • We're not starting from a greenfield position as both first versions of the glossary and terminology templates have already been through thorough editorial reviews.
  • It will give us a a better base to look at how we tie in the work of Rob Atkinson, Michael Jastram, etc. in regards to investigation of machine readable terminology systems, the scalability of them and our recommendations in regards to this.

Disadvantages

  • We are perhaps ignoring a valid use case. i.e.: "I just want to find out how to create a simple glossary for my project".
  • It could be thought that we're "doing away" with prior work, although I'd argue that we're simply building on the back of that previous great work.

Versioning and doc review process

Versioning this change directly in Git is going to make it a lot more manageable than transferring everything (i.e. both sets of docs) out into a Google doc and back again into Git. It's going to be a lot easier to see what's changed if we manage this change in Git directly. For example, we'll be able to see clearly which parts of the glossary template have been added to the current terminology system one, and where. Cameron is on board with this approach.

Also, as this change will undergo a slightly different review process than a "regular" template review, I will outline what reviewers should be looking for in the merge request itself.

Further considerations

  • After merging, the "original" templates should be removed from the repo.
  • The glossary template should be removed from any template pack it's part of and be replaced by the terminology one where applicable.
  • GDP partners (e.g. JetBrains)
Edited by Ian Cowley