Requirement writing

•  "When [condition] the [device] MUST [do something]."

It's surprising how many ways we can get this pattern wrong. This presentation walks through the requirement-writing-guide used by Google Chromebook engineers, and open sourced into The Good Docs Project. It covers:

• Business drivers behind requirements management.
• Writing rules to follow.
• Broader systemic challenges to be faced.

It draws upon engineering standards and best practices.

• Slides (cleaned for public release).
• Video (23 mins).

Open Source awards for Good Docs contributors

Congratulations to Google's Open Source Peer Bonus award winners. Winners from The Good Docs Project include:

Felicity Brand

Felicity Brand has been an incredibly impactful contributor within The Good Docs Project.

• She is one of the project’s founding members, and an active contributor to the Project Steering Committee.
• She regularly comes up with innovative and practical ideas, usually backed by deep background knowledge.
• She is regularly supporting others, focusing on key areas that need help. Most recently she has been playing a lead role developing a Content Strategy, Website Architecture, and development of project blogs.
• When boring but important things need to get done, Felicity is regularly stepping in to help out.
• And her fun, supportive and encouraging style is contagious. It makes those around her want to help.

In Felicity's words:

“I’m very pleased and proud to receive a Google Open Source Peer Bonus award. I was nominated for my contributions to The Good Docs Project where we are creating technical writing templates to help other projects create high-quality documentation. I’m passionate about the work we’re doing there, and have been hanging around the project since its inception in 2019. This is a friendly, inclusive community creating a safe space for folk to dip their toe into open source. We are global, and new folk are always welcome.”

Bryan Klein

Bryan Klein is a technical wizard when it comes to setting up documentation based infrastructure. He has been setting up or advising on much of the infrastructure behind The Good Docs Project, a project developing templates, processes and tools to help developers write great documentation.

• He is one of the main drivers behind a “Doc tools easy button”, a bold initiative to build the toolchain a for a docs website based on templates from The Good Docs Project.
• He is an active contributor to the Project Steering Committee.
• He is fun, supportive, encouraging, is quick to jump in and help others when they get stuck. He is one of the key people behind our unofficial tech-help channel

In Bryan's words:

“I've been actively working on open source projects since my time at NIST with the FDS project starting in 2006. More recently with The Good Docs Project (TGDP) since 2020. It's been a very rewarding experience to contribute to TGDP, with such an amazing diversity of participants, perspectives and interests involved. To be given recognition through the OSPB program was a pleasant and unexpected surprise. While it's not at all what I am participating in the project for, it feels great to have someone else in the project bring my name up for this award. Thank you to TGDP and to Google for this honor.”

Aaron Peters

Aaron Peters has been bringing his project management expertise to The Good Docs Project.

• Aaron has been a long term contributor to the project, and is an active member of our Project Steering Committee (PSC).
• He coordinates our Request of Comment (RFC) update process.
• He has led the development of our baseline development and release process.
• And he has been researching and setting up the supporting tool chains.

All his foundational work is setting up our project to achieve quality at scale.

Serena Jolley

Serena Jolley deserves recognition for generously sharing her deep experience as a User Experience (UX) designer with The Good Docs Project.

• She established a heartbeat in our previously dormant “Chronologue” working group – a group creating a fake project which our documentation templates will create examples for.
• She’s played a vital role creating well-thought out wireframes for the fake project.
• She shares her knowledge with her teammates by being transparent and explaining her methodology, and has specifically mentored a junior UX designer along the way.

Without Serena, this working group wouldn’t have achieved its current momentum.

Ian Nguyen

Ian's been working within our Chronologue working group, which is creating a fake project which our documentation templates will create examples for.

• Ian is the craftsman who has been building the fake product our group wants to document.
• He has been designing and implementing an API to retrieve data for events.
• He has turned wireframes into code, and he has been building a tangible web experience for the Chronologue project.
• Without his creativity and technical aptitude, we would not have a “fake” product to document.

Tina Lüdtke

Tina was ineligible for the Open Source Peer Bonus, as she was hired by Google as an employee. Instead she was awarded a Google Peer Bonus.

Tina has led our “fake example project” makes excellent contributions to the Content Strategy, Blog, and Book Club groups, and is an active contributor to the Project Steering Committee.
Check her post 6 Resources for Starting Your Journey Into Docs.

When to call in us tech writers

In a knowledge economy, effectiveness depends upon transferring ideas between people.

Technical writing is the art of optimizing the communication pipes.

Good documentation provides:

Just enough info,

When it is needed,

To support a specific action,

At the quality required.

This presentation highlights the key principles of technical writing, and when to call in us technical writers.

• Slides.
• Video (6 mins).

Open Source Peer Bonuses for Good Doc Templateers

 Congratulations to five templatateers from The Good Docs Project for your Open Source Peer Bonus award from Google.  This cool award enables Google employees to recognize and thank a few valued open source contributors. It includes a token financial contribution - enough to take the family out for dinner at a nice restaurant.

Gayathri Krishnaswamy, Chris Ganta and Nelson Guya

Gayathri, Chris and Nelson have been peer-writing open source documentation templates within our EMEA-APAC working group. This includes:

• Deep research into “What is a good quickstart document”.
• Established a quickstart template and associated guide for documenting open source projects.
• Projecting their writing expertise into the external OSGeo-Live open source project.
• Establishing and describing "peer writing". Look out for their talk about their experience at the upcoming Write the Docs conference: Peer writing and beyond - An experimental approach to a sustainable open-source projects.

Notably call outs:

• As well as doing a lot of the research, Gayathri has managed the copying of docs from Google Docs into the github repository.
• Nelson initially worked out the OSGeo-Live documentation pipeline, and then mentored Chris and Gayathri in getting started.
• Chris did a lot of the group coordination, and has delivered an excellent presentation on the peer writing strategy that the group developed, laying foundations for how it can be replicated.

Carrie Crowe

Carrie has grown into a key role in within The Good Docs Project:

• She’s  head of the content strategy team, driving the project contributors to frame their work in terms of understanding our user bases, accounting for where individual elements of our project need to live.
• Specifically, in the last year she’s helped the project clarify its scope and focus, with the ideals of providing education to developers needing to write docs, templates for different types of docs, systems for deploying docs, and related doc subjects. That’s all thanks to her stepping in as a product manager to organize a big group of volunteers, alongside her technical writing skills used in article and template contributions.
• In recognition of her work, she's recently accepted a co-chair role of The Good Docs project.

Deanna Thompson

Deanna Thompson is an experienced technical writer who plays an impactful role within The Good Docs Project.

• She done extensive research and community consultation to build a template for writing tutorials that developers can use.
• She continually provides insightful feedback to templates others develop, showing leadership and mentorship our team greatly benefits from.
• She's been playing a lead role in establishing training for using git for tech writers within our project.
• And in recognition of her work, she has recently accepted a role on the Project Steering Committee.
• She’s certainly raised the bar on what we hope to get out of contributors!

Curly Beach to Forestway by bicycle

Cycle from Curl Curl beach back to Forestway via bike paths, back streets, and a short stretch of dirt trail.

10 kms. 30 mins.

Enjoy the journey!

 

My Open Source Docs addiction

 

Why am I addicted to open source docs?

• "Giving back" adds extra meaning and purpose to my life.
• It's impactful.
• I can tackle wild moon-shot ideas.
• I can choose to do-it-right over short-termism.
• I am often working on the cutting edge.
• I can choose morals over profits.
• I get to collaborate with a community of like-minded souls.
• It’s a fun, safe and engaging way to learn, and looks great on a resume.
• The world desperately needs doc heros, and as a tech writer I'm uniquely qualified to help.
• I've uncovered my alter-ego:

Version 1.0 of this lightning of this talk was presented at an internal tech writers event in January 2022, and a tweaked 2.0 was presented at Write the Docs Australia, December 2022.

• Video
• Slides

Frenchs Forest to Warringah Mall by bicycle

Want a quick, 20 minute, pleasant and safe bicycle route from Frenchs Forest down to Warringah Mall? Try this: 

Cycle from Frenchs Forest down to Warringah Mall via bike paths, back streets, and a short stretch of dirt trail.

Enjoy the journey!

Defining good

Within non-trivial technical projects, it helps to have a common language to describe "good":

• It enables cross-feature comparisons and prioritization.
• It facilitates conversations between stakeholders, business and developers.

This page suggests a feature quality scale, along with how it can be applied.

Quality scale

A quality scale can be applied to:

• Business goals, stakeholder needs, features, quality, schedule, maintenance, and more ...

	User experience	Description	Requires
Qx	Over-deliver	* Functionality cannot be noticed or used by the user.
Q5	Delight	* Anticipate user desires, and provide it.	* Understand the user’s desires and passions.
Q4	Impress	* Anticipate user unanticipated needs, and provide it.	* Analyze the user behaviors and needs. * Understand the product capabilities. * Establish critical user journeys.
Q3	Satisfy	* Meet user’s known wants.	* Listen to the user’s asks.
Q2	Underperform	* Under specified or poorly implemented. * User experience includes many micro-frustrations.	* Meet purchasing authority’s specification. * Cost saving implementation. * Minimal testing.
Q1	Not practically functional	* While the product “works” the experience is so poor that the user chooses to use something else if available.
Q0	Broken	* Functionality doesn’t work at all.

Possible quality scale

Quality categories for each feature

For each feature, a project can define quality categories.

Feature	Delight	Impress	Satisfy	Underperform	Not practically functional	Broken
On/off button			Works			Fails
Waterproof to		> 100m	> 10m	> 1m		< 1m
Uptime	> 99.999%	> 99.99%	> 99.9%	> 99%	> 90%	< 90%

Example quality criteria

Note: Many features won't need the full scale.

Phase exit criteria

The importance of each quality criteria will vary depending upon:

• Different products.
• Different features.
• Different development phases: alpha, staging for test, production/stable release.

Phase: Alpha release

Feature	Priority	Should	Must	Error tolerance
On/off button	P1	Satisfy	Satisfy	Satisfy
Waterproof	P3	Impress	Underperform	Broken
Uptime	P2	Impress	Satisfy	Underperform

Example phase exit criteria

As requirements

The criteria can be converted into traditional requirements:

The device	should	be waterproof to 100m.
The device	must	be waterproof to 1m.

Example requirements

Bug severity levels

Terminology from the quality scale can be aligned with bug severity levels. Severity can be driven by impact to the user, or impact to the business.

Severity	User Impact	Business Impact
S4 Trivial	* P3 feature underperforms	* Person days to fix.
S3 Minor	* P3 feature is broken * P2 feature underperforms	* Person weeks to fix.
S2 Major	* P1 feature is broken, with work-around * P2 feature is broken, no work-around	* Person months to fix.
S1 Critical	* P1 feature is broken. No work-around.	* Upcoming releases blocked until fix provided.

Example severity scale

Open source peer bonuses

 

Congratulations Alyssa, Angelos and Aiden for your Google's Open Source Peer Bonus award.  This cool award enables Google employees to recognize and thank a few valued open source contributors. It includes a token financial contribution - enough to take the family out for dinner at a nice restaurant.

Alyssa Rock

Alyssa has played a pivotal role in growing and expanding, The Good Docs Project. She has been doing this by:

1. Being an excellent technical writer, prolifically writing quality material for the project.
2. Reaching out at conferences and related events, advocating for the project, and attracting scores of new contributors.
3. Pro-actively helping establish a very supportive and inclusive culture, leading by example, being incredibly warm and encouraging in helping to onboard people, and writing our code-of-conduct.
4. Stepping up to do much of the grunt work to establish community processes.
5. Doing the many other small things that help make an open source project successful.

Angelos Tzotsos

Angelos has been a lynch pin contributor to many of the geospatial open source projects. Most notably, he is one of the primary coordinators of the OSGeo-Live linux distribution of open source geospatial software, supporting the 50+ projects represented to get the software up to scratch and compiling on the distribution. He is very competent, always humble, very wise, always supportive of others, and very effective at building open source communities. Notably, he has been voted onto the board of the Open Source Geospatial Foundation.

Aidan Doherty 

Aidan has been a steady and reliable contributor to The Good Docs Project, taking on core background tasks, like community building (kicking off an unofficial welcoming committee for new members), and setting up a base template working group (from which all of the rest of our project templates will depend.) He takes on the unglamorous but important work which makes an open source project successful.

Timeless documentation

Big Ben clock

Maintaining docs for an evolving software baseline is a constant pain for us technical writers. I'm often helping developers remove time based language from docs, and was surprised that I couldn't find best practices on how to apply this.

So we've added a timeless documentation section to the Google developer documentation style guide. Timeless documentation is documentation that avoids words and phrases that anchor the documentation to a point in time or assume knowledge of prior or future products and features. So while it is okay to reference "a new feature" in news article; "latest" or "new" shouldn't be used in reference docs. The content becomes outdated soon after publication.

You can read more about it in the Google developer documentation style guide.

Walk your bike into the car park!

TS;DR (Too Sarky; Don't Read)

I've been riding to work for around 30 years, and every year or two you see an email such as this, and it makes me laugh every time.

Dear cyclists,

For your health and safety, please ensure that you always dismount and walk your bicycle to the car park's bike cage.

Thank you and stay safe,

Office facilities.

So here is my response:

Dear facilities,

On my ride to work I encounter:

• Squeeze points on main roads shared with cyclist killing machines,
• Stressed and agro peak hour traffic,
• Super slippery road plate,
• Unmaintained and destabilizing bike paths,
• I could go on ...

And in the last 50 metres of my ride, travelling at walking speed into a quiet car park, where the worst that could happen is I might slip on polished concrete and bruise a hip; at that point my employer becomes concerned about my safety and encourages me to walk my bike?

(This is not a complaint, or an ask for action. Just an opportunity to share in the humour of the situation.)

One of your friendly cyclists.

Doc templates workshop

The Good Docs Project is about to run a series of one hour workshops to brainstorm:

• What constitutes a good doctype template?
• How should we capture and present best practices in our base template docs?
• Which templates should be worked on next?

When

We'll start around March 17, 2021. If you’d like to contribute, please vote for your preferred time slot and help us understand how many people will attend: Doodle poll.

Feedback will be used to update our base template, and set the direction for future template development.

Sessions

Pre-reading:

• To contribute meaningfully you should read our base template docs, and be ready with questions or suggestions.

Session 1: Overview

• Walk through of our current base doctype template
• Explain logic behind each section
• Field questions
• Identify topics to discuss in future sessions

Session 2,3: Topic discussions

• Deep dive into topics identified in session 1
• Absorb actions to update the base template
• Volunteers to test theories by starting to write a template

Why participate

Participate if:

• You are keen to help shape best practices in doctype templates.
• You’d like to adopt a basetype template.
• You have expertise, bandwidth and commitment.

Background

To date:

Within The Good Docs Project we are creating best practice templates and writing instructions for documenting open source software.

In our first release in 2019, we’ve created 0.1 core templates, based on insights from multiple senior tech writers. These are quite good, but in the interim we’ve been improving these templates, building up processes, and refining our thinking about what makes a good template.

This has accumulated into our current base template docs. As of March 2021, these docs are draft ready, but untested.

This phase (first half of 2021):

Next we are inviting tech writers to adopt and create a template from our prioritized wish-list of templates to write. We will be testing our base template by using it - and we will collect feedback into the base template.

Adopting a template is a reasonable commitment, but is achievable for one person to tackle. It involves:

• Learning the base template.
• Researching and documenting best practices in use for your doctype.
  • This typically involves researching business processes and communication theory.
• Collaboratively refine the template with others.

We’ll move through stages of:

• Nothing -> Something -> Better -> Best

At the end of this push, we expect to have a more consistent, core set of templates, along with a bunch of lessons to roll into future phases.

Future:

In future:

• We’ll refine our templates drawing upon the lessons we’ve learned.
• We’ll expand the range of templates we cover.

Open Source Documentation Panel - Contributing.today

 

I joined a panel at Contributing Today talking about open source documentation with:

• Scott Riley, product designer Gitbook, author of Mindful Design
• Lorna Mitchell, developer advocate Aiven, maintainer rst2pdf
• Jen Weber, web developer and writer at Ember.js

Some of the topics we covered:

• What are good docs and exemplars?
• Should different specializations be used for different doc types?
• Where to start learning about being a tech writer?
• How to improve docs for your project?
• Making your open source project attractive for tech writers to join.
• Accessibility.
• Doc strategy, information architecture, processes.
• Gitbook, The Good Docs Project, Season of Docs, rst2pdf.

Tweak Google's mission?

Google has an awesome mission statement:

"To organize the world's information and make it universally accessible and useful."

Its hard not to feel inspired by this. What a valuable gift to the world! But I think it could be even better. Because this mission statement only kicks in after ideas have been written down, as “information”.

• What if we could help capture all good ideas?
• What if we could help everyone to explain their best ideas clearly and concisely, in a form that can be easily shared and understood?

This is the mission of The Good Docs Project: 

"Create best practice templates and process for open source software."

If combined, Google’s mission could become even better:

"Organize all the world's information ideas and make them universally accessible and useful." 

Cycle Manly to Frenchs Forest

Here is a beautiful ride from Manly to Frenchs Forest using only quiet backstreets, cycle paths, tracks and fire-trails.

Cycle Manly to Frenchs Forest.

Enjoy the journey!

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.

Tech Writing Patterns and Anti-patterns

This presentation summarizes a larger essay of Patterns and Anti-patterns and suggests ways to help solve the associated challenges. It is mostly based on experiences learned within volunteer open source communities. [Slides updated 2021-04] [Original slides].

Awards for open source tech writers Jo and Jared

Jo Cook and Jared Morgan have been presented with awards for Google's Open Source Peer Bonus Program. The award is a recognition and thank you to people who go above and beyond in their contributions to open source. It also includes a token financial contribution - enough to take the family out for dinner at a nice restaurant.

Well done Jo and Jared, you really deserve it:

Jared Morgan, Write the Docs podcast host

Jared Morgan

Jared is a core contributor and community builder within The Good Docs Project. As an experienced technical writer, he has contributed to many of our initial set of writing templates and then helped absorb feedback from our community. He is well respected and well connected within the technical writing community, helping to inspire other thought leading technical writers to come and join us.

This year, 2020, he has signed up as a Season of Docs mentor for The Good Docs Project.

In a related activity, he has also helped spread knowledge within the technical writing community, by co-hosting the Write the Docs podcast.

Jo Cook, explaining docs at DevRel conference

Jo Cook

Jo is an enabler of open source communities. She commits large chunks of her volunteer time to working on the hard problems that others don't tackle. She is someone you can rely upon when needed, and she steps back when her skill-sets are more valuable elsewhere.

A few highlights of her volunteer activities over the last couple of decades include:

• Help set up The Good Docs Project, doing much of the grunt work in setting up open source processes.
• Mentoring a Season of Docs tech writer and other community contributors for the GeoNetwork project.
• Presenting at numerous conferences on topics of open source, documentation, and geospatial.
• Playing lead roles in setting up conferences for the Open Source Geospatial foundation.
• Building the Portable GIS distribution of Open Source Geospatial software.
• Serving on the board of the international Open Source Geospatial foundation (OSGeo).
• and more ...

Cross-domain management of glossaries

Image by Chris Dlugosz

Glossaries are easy to set up for simple examples but very hard to scale - especially when you try to scale across use cases, across domains and across organisations.

We are kicking off a pilot project to address cross-domain management of glossaries and preferred word lists. The pilot will build processes and tools for the generic use case, developing and applying them within the geospatial mapping domain.

Communication about this document will be on the OSGeo Lexicon email list. (Check your spam for confirmation email after subscribing.)

Goals

We aim to achieve the following:

• Create best practices in cross-domain glossary management, for adoption by the technical writing community.
• Build a community who define and manage geospatial terms across multiple geospatial communities.

Use cases

This project is designed to address the following use cases:

1. As a general document reader, I want to find definitions for the terms and acronyms in the document I am reading. There may be multiple definitions for a term, determined by context, or having multiple upstream source definitions.
• Ideally identified terms can be highlighted, and readers can hover over terms to get a popup with more information.
2. As an advanced document reader or term maintainer I want to understand the inheritance path back to upstream source definitions.
3. As a technical writer, I want to find the preferred spelling, capitalization and word choice for a term.
4. As a technical writer, I want a tool which builds a glossary of the organisation specific terms used within my document, by searching my organisation’s glossary.
• As a minimum, this will search a document for acronyms, and match against provided glossaries.
• Missing or duplicate terms will be flagged.
• Existing terms will be highlighted according to [preferred, alternative, deprecated] status.
5. As an organisation, I’d like a tool which seeds my organisation specific glossary by searching my organisation’s docs for terms in a superset of reference glossaries.
6. As a document translator, I want glossary terms to be translated into my target languages, so I can consistently translate a source term to the same target term.
7. As a project, I want a glossary which includes terms specific to my project, as well as terms sourced from multiple external glossaries.
8. As a foundation, I want a glossary which sources terms from my many sub-communities.
9. As a glossary owner, I want to ensure my glossary is continuously updated to align with updates in my source glossaries.
10. As a glossary owner, I want a governance framework to help resolve terminology management conflicts between terminology sources and stakeholders.
11. As a software developer, I want terms and relationships between glossaries in a machine-readable form so that I can integrate glossary functionality into software.
12. As a data modeller, I want the terms described in my model to use existing term definitions, (from APIs, standards, etc), as defined within my domain, so that I can share my terms with others, and seamlessly integrate datasets from multiple sources.
13. As an application using a glossary, I want terms defined with a consistent schema which facilitates machine readability and interoperability
14. As a researcher, I want to be able to find related information even if it uses different terms for the same concepts.
15. As a content manager, I want to apply a preferred term as metadata to enable retrieval of digital content across disparate source repositories.
16. As a search engine or software algorithm building knowledge graphs, I want to use glossaries to help extract meaning from textual information sources.

Scope

The pilot project will focus on the geospatial domain, which has an advanced ecosystem of stakeholders and technologies. However, the templates and processes will be developed to be broadly applicable for all software ecosystems managing glossaries.

Schedule

• August 2020: Kickoff
• December 2020: Soft launch at the Write the Docs Australia/India conference
• February 2021: Hard launch

This schedule aligns with The Good Docs Project's Season of Docs initiatives.

Deliverables

The following deliverables are likely to be achieved within the pilot’s timeframe:

Schemas

1. Schema for a preferred word list. For example: Word list | Google developer documentation style guide.
2. Schema for a term definition. For example: ISO/IEC Directives art 2, Principles and rules for the structure and drafting of ISO/IEC documents - 16.5.5 Term and 16.5.6 Definitions.
3. Schema for translation of terms between languages

Processes

1. Process for a central glossary owner to accept, triage, and refine proposals for new terms from their community:
• As single terms.
• As a curated set such as a word-list from an authoritative source.
2. Process for deciding the point of truth for a term within a glossary, be that from a central glossary or from a leaf glossary.
3. Process for handling multiple definitions of a term, which may differ across contexts.
4. Process for notifying updates to a glossary.
5. Process for managing the lifecycle of terms.
6. Version management of individual terms.
7. Version management of schemas.
8. Version management of a glossary as a whole.
9. Version management of processes.
10. Version management of tooling.

Guides

1. How-to guide for a project to set up their own glossary by selecting a subset of master glossaries plus adding their own terms.
2. How-to guide for setting up a master glossary.
3. How to handle aggregation and overlaps between sets of terms and mappings between similar terms used in different contexts.

Tools

1. Tool for managing glossary terms through a standards based lifecycle such as OGC’s statuses:
• Submitted
• Accepted
• Experimental
• Valid
• Superseded
• Deprecated
• ...
2. Tools for publishing a glossary in human readable form,
3. Including key relationship visualisation and navigation support.
4. Tool for publishing a glossary in machine readable form,
5. Facilitating features such as mouse-over popups.
6. Tools for exporting from a master glossary into other publishing mediums, such as a page within another website or Content Management System (CMS).

Geospatial domain deliverables

1. Term management committees:
• OSGeo Lexicon committee managing OSGeo terms.
• OGC Naming Authority committee managing policies and final publication for OGC geospatial standards terms.
• ISO TC211 committee managing ISO geospatial standard terms.
• [Optional] Specific software project committees managing their project’s terms.
2. Definitions for OSGeo terms
3. Translations of OSGeo terms
4. Glossary Web Services:
• OSGeo Foundation Glossary Web Service.
• OGC Glossary Web Service.
• ISO TC211 Glossary Web Service.
• [Optional] Multiple OSGeo projects standing up their own glossary instance. For instance, set up one for QGIS and/or PostGIS.
5. Publishing glossaries:
• Publishing of Glossary within Geoforall Newsletter
• Publishing of Glossary within OSGeoLive documentation

Why now? Why Geospatial?

As of August 2020, many things are lining up to enable us to collectively solve the tough challenges around the cross-domain management of glossaries.
Aligning activities include:

1. The Good Docs Project has been making progress tackling technical writing problems. We have recently built a How to apply/customise a writing style guide for software projects. A next step is to explain how to apply word lists and glossaries. And we have volunteers willing to push this forward.
2. The geospatial community is very advanced at trying to solve terminology management challenges:
• Through the OSGeo Foundation, we have relationships with ~ 50 geospatial open source projects who all need glossaries, and through the OSGeoLive project we have contact points with each of these projects as well as access to volunteer translators for OSGeo documentation. In the 2019 Season of Docs program we connected with all these communities and updated their quickstarts. We can do it again for glossaries.
• We have experienced volunteers from the OGC and ISO TC211 standards bodies keen to bring their expertise to advance this challenge. These volunteers are already working on this problem.
• From the ISO TC211 and OGC communities, we have access to open source software for term management and access to the people who wrote it.
• Through the Geolexicon working group, we have OSGeo volunteers who have been maintaining a glossary of terms. They will be able to apply these terms and add more.
3. The Good Docs Project is starting a sprint of work, aligned with Google's Season of Docs. We are shooting for a soft launch in December 2020, hard launch around February 2021. This helps frame a sense of purpose, timing, and scope which we can tap into.
4. There are other initiatives within The Good Docs Project which will complement this work and facilitate cross-pollination of ideas.
5. ISO/TC 211/TMG is redeveloping its Multi-Lingual Glossary of Terms (MLGT) as an ISO SMART project for machine-readable/interpretable terminology that encompasses management of life- cycle to the usage of such content.
6. The ISO/TC 211 MLGT SMART work is performed in partnership with Ribose who supplies the Glossarist software and the Geolexica terminology web platform. Ribose volunteers to support OSGeo lexicon work and its workflow in both of these offerings.

Postnote

A variant of this blog was picked up by the OGC.