Season Of Docs 2021 Proposal

Cross-organizational glossaries guide - OSGeo Foundation

This is a proposal to have a technical writer sponsored under Google’s Season of Docs to:

• Document processes for establishing cross-organizational glossaries.
• Support others set up pilot glossaries within some of the geospatial open source projects.

About OSGeo

The Open Source Geospatial Foundation (OSGeo) is a not-for-profit organization whose mission is to foster global adoption of open geospatial technology by being an inclusive software foundation devoted to an open philosophy and participatory community driven development. OSGeo works with organizations worldwide promoting open source geospatial.

Cross-organizational glossaries project

Glossaries are easy to set up for simple examples but extremely hard to scale - especially when a project wants to inherit or share terms with other organizations.

The cross-organizational glossaries project covers software, information schemas and best practice processes required to set up and manage glossaries which have interdependencies with other glossaries.

It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.

Backing organizations

The project is jointly backed by volunteers from multiple organizations:

• The Open Source Geospatial (OSGeo) Foundation
  • An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.
  • The OSGeo Foundation is heading this Season of Docs proposal.
• The Good Docs Project
  • An open source community of technical writers building best practice templates and writing instructions for documenting open source software.
  • A best practices glossary template and how-to guide is to be developed as part of this project.
• The Glossarist open source project
  • A project dedicated to standing up and managing standards based, interoperable glossaries.
  • This software is for government sized glossaries and is based on best practice standards.
  • This software is being used within the project.
• The Open Geospatial Consortium (OGC)
  • An international geospatial standards setting body.
  • The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.
• The ISO/TC211 geospatial standards committee
  • A committee managing geospatial glossary terminology.
  • This committee is providing terminology, and mentoring in managing terminology.

Mentors

The following glossary project community members have offered to act as volunteer Season of Docs mentors for this project. Each brings a unique set of skills to the project and collective creates a robust community.

Ilie Codrina Maria

• OSGeo Foundation board member

Nikos Lambrinos

• Geography Professor
• Chief Editor of GeoForAll Newsletter and GeoForAll glossary
• (GeoForAll is an initiative under the OSGeo Foundation)

Cameron Shorter

• One of the coordinators of The Good Docs Project
• Ex OSGeo board member, and open source project coordinator/contributor
• Tech writer at Google

Rob Atkinson

• Expert on structured data, schemas, glossaries, interoperability, …
• Open Geospatial Consortium staff member

Ronald Tse

• Lead developer of the open source glossarist software being used
• ISO/TC 211 and OGC member

Reese Plews

• Primary author of the ISO/TC 211 Terminology Management Group’s glossary

Ankita Tripathi (if not engaged as the tech writer for this project)

• Technical Writer
• Project Steering Committee member of The Good Docs Project

Umbrella project

The cross-organizational glossary project is a bit unusual in that it is acting as an umbrella project, with much of the generated material being deliberately kept inside other projects.

For evidence of a mature and active community, refer to:

• Geospatial glossary terms, compiled by our team.
• The Good Docs Project templates repository, where the glossary template will fit.
• Docs repository for the OSGeo-Live distribution, where we intend to add glossary entries.
• Glossarist github repository, which stores the glossary software.
• Minutes from weekly meetings.

Season of Docs focus

From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:

• Existing documentation has immature glossaries - if one exists. And while there is significant overlap in the terminology used between projects, there is minimal integration and coordination in glossary terms. This hinders communication about common concepts.

From our cross-organisational glossary’s project perspective:

• While our team has collated significant best practices expertise, it hasn’t been collated in explanations and how-tos which are easy-to-follow by everyday people wanting to stand up an interoperable glossary.

The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.

Season of Docs scope

In scope

Deliverable: Cross-organizational glossaries concept document

• This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:
  • Why you should care.
  • When you should care.
  • What should you care about.
  • Options and recommendations for information schemas.
  • Options and recommendations for governance.
  • Relevant standards.
  • References to further research.

Deliverable: glossary-template and glossary-template-guide

• These template documents will align with the base-template provided by The Good Docs Project, and will provide practical guidance on how to set up a glossary.

Deliverable: Support pilot projects testing the documentation

• The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.
• This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.

Deliverable: Project Case Study

• The tech writer will act as the primary author of a case study in the success and challenges faced during the Season of Docs project.
• This case study will be co-authored by the project mentors, and interested community mentors.

Source material

Source material is to be collated from existing team material and know-how.

Quality

As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.

We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.

Out of scope

• Installing or configuring specific glossaries. This will be the responsibility of participating projects.
• Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.
• Establishing governance processes for a specific glossary.
• Establishing a measurement framework for the success of this project.

Potential tech writers

We have a tech writer, Ankita Tripathi, who we would like to engage for this project.

• Ankita is a professional technical writer.
• She has been actively involved in both the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem
• She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.

If Ankita’s availability changes, there are others in our community we could approach.

If our project is selected, we intend to engage our technical writer soon after the April 16 selection date. This should spread the workload and mitigate schedule risk.

Measuring Season of Docs success

There is a difference between metrics we’d like to have compared to metrics which we can easily and sustainably measure within our community. Here we list what we think we can sustain, described using (Goal, Indicator, Metric).

Goal: Help communicators reduce cognitive load

Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators

Sub-goal: Provide a scalable framework for cross-organizational glossary management

Sub-goal: Reduce effort required for cross-organizational glossary management

• Indicator: Projects stand up standards compliant glossary services
  • Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.
    • Success criteria: Within the project timeframe, we will consider this project a success if two glossaries are stood up and interoperate with each other, based on instructions provided.

Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management

• Indicator: Explanation document is read
  • Metric: Count the views of an explanation document
    • Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.

Project budget

Item	Amount $US	Notes
Technical writer	4,500
Supporting organization overheads	300	Incidentals such as bank processing fees, and general good will.
Swag	200	Due to our high mentor:writer and likely high community:writer ratios, we would prefer to invest more than the $200 minimum for goodwill with our community. Details to be confirmed, but may cover something like 10 tee shirts for volunteers.
Total	5,000

Additional information

• The OSGeo Foundation, The Good Docs Project, and some of our mentors have participated in both Google Season of Docs and Google Summer of Code.
• Some of our mentors and participating community members are professional technical writers.
• Our mentors collectively have decades of experience with structured data, glossaries. They are also associated with international standards bodies which enables us to both learn from and influence these bodies.

We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.