Thursday 3 December 2020

State of The Good Docs Project

Lightning talk summarizing the status of initiatives within The Good Docs Project.
Presented at Write The Docs - Australia and India. Source slides.

Wednesday 2 December 2020

Halfway status - glossary pilot

This interim status report outlines achievements, early findings and outstanding tasks for our cross-organizational glossary pilot project.

Pilot Overview

Glossaries are easy to set up for simple examples but extremely hard to scale - especially when a project wants to inherit terms from other organizations. This pilot has been set up to test cross-domain management of glossaries. We started in August 2020, and plan to have tested pilot goals by March 2021.

We are testing glossary software, standards, and processes, and applying them to cross-organizational use cases within the geospatial mapping domain.

For more details, refer to our manifesto.

Pilot contributors: Cameron Shorter, Alyssa Rock, Ankita Tripathi, Naini Khajanchi, Ronald Tse, Reese Plews, Rob Atkinson, Nikos Lambrinos, Erik Stubkjær, Brandon Whitehead, Ilie Codrina Maria, Vaclav Petras

Current status

Our interim status as the start of December 2020 is as follows:

Task % Complete
Define glossary goals 90%
Establish implementation Plan 80%
Establish a healthy community 70%
Implement/adopt software platform 70%
Establish schemas for terms 70%
Define sentence structure for terms 70%
Connect external glossaries 10%
Collate and clean Open Source Geospatial (OSGeo) terminology 60%
Document template governance processes 10%


Task: Define glossary goals.

Understanding the problem is the first step needed to then address it.

Connected Glossaries

Figure: Connected glossaries, source


Implementation plan

Task: Establish implementation Plan


  • Within the Glossary Pilot Manifesto we articulated steps for standing up a cross-organizational glossary pilot. We have been steadily working against this plan.


Task: Establish a healthy community:

Apache, one of the leading open source foundations prioritizes “community over code”. A strong community will solve any technical challenges faced.


  • We have attracted a motivated, competent, and cross-functional team of 5 to 10 people (depending on how you count), who are steadily working through our backlog of tasks. Collectively we have decades of experience with glossaries, tech writing, standards, software, and the geospatial domain we are initially focusing on.
  • We have a weekly status meeting, sometimes complemented by additional meetings, along with a slack channel, and email list.


  • We have only attracted one of the many OSGeo open source projects to sign up as a pilot. This is likely because we haven’t made the signup process easy enough yet, and our tools and processes need improving.
  • After completing the pilot and releasing an alpha version, we’d want to scale our community into other domains (beyond our current spatial domain focus).

Glossarist platform

Task: Implement/adopt software platform


  • We’ve adopted the glossarist open source software to manage terminology. This provides terminology management of terms, and publishing of terms via a standards based web service.
  • Ribrose, who develop this software, has been working with us to update the software to address use cases and feedback we are finding during testing.
  • Extra functionality is expected to be included during the remainder of this pilot.


Task: Establish schemas for terms

Cross Organizational Glossary Schema

Figure: Glossary schema, sourcing from upstream glossaries, source


Sentence structure

Task: Define sentence structure for terms.


Connect glossaries

Task: Connect external glossaries


  • In theory, we are very close to connecting two glossaries. In practice, we still need to set this up, which is a focus for the rest of this pilot.


Task: Document template governance processes

Glossary governance

Figure: Glossary governance, source


While we have been discussing and making use of our own unwritten governance process, we are yet to write this down and provide it as template guidance.

Spatial use case

Task: Collate and clean Open Source Geospatial (OSGeo) terminology


  • We’ve collated OSGeo terminology from around ten OSGeo glossaries along with OGC and ISO terms.
  • These terms have been aligned with writing rules.
  • We’ve just started looking at terms from the GRASS project, and plan to integrate these too.