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.

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%

Goals

Task: Define glossary goals.

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

Figure: Connected glossaries, source

Status:

• We feel we have articulated the problem and associated use cases reasonably well. Refer to the Glossary Pilot Manifesto and accompanying presentations.

Implementation plan

Task: Establish implementation Plan

Status:

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

Community

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.

Status:

• 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.

Outstanding:

• 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

Status:

• 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.

Schema

Task: Establish schemas for terms

Figure: Glossary schema, sourcing from upstream glossaries, source

Status:

• We’ve adopted the Simple Knowledge Organisation System (SKOS) standard for selecting the fields to use when describing terminology.

Sentence structure

Task: Define sentence structure for terms.

Status:

• For sentence structure, we’ve adopted 16.5.6 Definitions, ISO/IEC Directives, Part 2
  Principles and rules for the structure and drafting of ISO and IEC documents
• “The definition shall be written in such a form that it can replace the term in its context. …”
• Example: 2.1.17 die: metal block with a shaped orifice through which plastic material is extruded
• While aligning with uses in specific spatial ISO settings, many glossaries use alternative sentence structures, and this is something I’m expecting we’ll need to revisit.

Connect glossaries

Task: Connect external glossaries

Status:

• 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.

Governance

Task: Document template governance processes

Figure: Glossary governance, source

Status:

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

Status:

• 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.