https://wiki.osgeo.org/w/api.php?action=feedcontributions&user=Wiki-Camerons&feedformat=atomOSGeo - User contributions [en]2024-03-30T03:55:07ZUser contributionsMediaWiki 1.35.9https://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=126383Lexicon Committee2021-03-27T05:25:08Z<p>Wiki-Camerons: Code of Conduct</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeodev.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Projects ==<br />
* [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/ Cross domain glossary management]<br />
<br />
== Resources ==<br />
* [https://osgeodev.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]], chair (OSGeoLive, The Good Docs Project)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* Alyssa Rock, technical writer and contributor to The Good Docs Project<br />
* Ankita Tripathi, Technical Writer and Contributor to The Good Docs Project<br />
* Naini Khajanchi, Technical Compliance Writer<br />
* Nikos Lambrinos, Geography Professor, Chief Editor of GeoForAll Newsletter, founder of the Hellenic digital earth Centre of Excellence<br />
* Erik Stubkjær, co-editor of the Cadastre and Land Administration Thesaurus (CaLAThe)<br />
* [[User:Brandonnodnarb|Brandon Whitehead]], Environmental Data Scientist, Manaaki Whenua – Landcare Research<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
* Felicity Brand, technical writer and Contributor to The Good Docs Project<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
== Code of Conduct ==<br />
We are respectful to each other, and welcoming, in line with [https://www.osgeo.org/code_of_conduct/ | OSGeo's Code of Conduct] policies.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021&diff=126382Season Of Docs 20212021-03-27T05:23:06Z<p>Wiki-Camerons: /* About OSGeo */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= OSGeo's Season of Docs 2021 home page =<br />
<br />
== Proposal ==<br />
OSGeo's Season of Docs [[Season_Of_Docs_2021_Proposal|detailed proposal]] is to build guides and processes for cross-organizational glossaries, focusing initially on projects within the Open Source Geospatial Foundation (OSGeo).<br />
<br />
== Background ==<br />
<br />
For 2021, OSGeo's Season of Docs proposal is to help address glossary challenges faced by many of OSGeo's projects.<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
The cross-organizational glossaries project covers software, information schemas and best practice processes required to set up and manage glossaries which have inter-dependencies with other glossaries.<br />
<br />
Our focus is initially on glossaries within the geospatial domain, but problems we solve will be directly applicable to other domains too.<br />
<br />
== Further Information ==<br />
<br />
Supporting project:<br />
* OSGeo's [[Glossary-Project|Glossary Project]].<br />
* Coordinated by OSGeo's [[Lexicon_Committee|Lexicon Committee]]. You can join the committee if you would like to get involved.<br />
<br />
See also:<br />
* Google's [https://developers.google.com/season-of-docs/ Season of Docs] site.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Code of Conduct ==<br />
We are respectful to each other, and welcoming, in line with [https://www.osgeo.org/code_of_conduct/ | OSGeo's Code of Conduct] policies.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Glossary-Project&diff=126381Glossary-Project2021-03-27T05:21:53Z<p>Wiki-Camerons: Code of Conduct</p>
<hr />
<div>The OSGeo glossary project is building processes and tools for setting up cross-domain, inter-operable glossaries. The focus is initially on OSGeo and spatial projects, but the patterns will be equally applicable and usable within other domains as well.<br />
<br />
== Goals ==<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when trying to inherit terms from other organizations. The collaborative overhead becomes overwhelming. Communities struggle to agree upon:<br />
* Term definitions,<br />
* Field and sentence structure,<br />
* Tooling,<br />
* Governance, and more. <br />
<br />
== Challenges ==<br />
Here we cover some of the key challenges we’ve been working through.<br />
=== Sharing Terms ===<br />
We’ve been working on how to share terms between glossaries.<br />
<br />
[[File:Sharing terms.png|400px|alt=Sharing terms between organizations]]<br />
<br />
=== Information Schemas ===<br />
We’ve been establishing standardized information structures.<br />
<br />
[[File:Information schema.png|400px|alt=Glossary schema elements]]<br />
<br />
=== Governance ===<br />
We’ve been working on governance models that projects can adopt.<br />
<br />
[[File:Governance real.png|600px|alt=Glossary governance processes]]<br />
<br />
=== Open-source software tooling ===<br />
For building better cross-organizational glossaries, we are using [https://www.glossarist.org/ Glossarist]: an open-source tool to create, maintain, and update glossaries hassle-free. Glossarist is already in use by the ISO/TC 211 spatial standards body. <br />
=== OSGeo Terminology ===<br />
We’ve established an initial [https://osgeodev.geolexica.org/ GeoLexica glossary] covering English terminology used within OSGeo.<br />
<br />
== Umbrella project ==<br />
<br />
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.<br />
<br />
Projects include:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].\== License <br />
<br />
==License==<br />
The open source licenses being used by us and these projects for documentation include:<br />
* [https://creativecommons.org/licenses/by/4.0/ CC-By]<br />
* [https://opensource.org/licenses/0BSD Zero BSD]<br />
<br />
== Next Steps ==<br />
In 2021 and onwards, we aim to achieve the following:<br />
* Create best practices in cross-domain glossary management, for adoption by the open-source and technical writing communities.<br />
* Build a community that defines and manages geospatial terms across multiple geospatial projects and communities. <br />
* Set up processes collated in explanations and how-tos which are easy-to-follow by everyday people wanting to stand up an interoperable glossary.<br />
<br />
We have applied to [https://wiki.osgeo.org/wiki/Season_Of_Docs_2021_Proposal Google Season of Docs 2021] which would help with achieving these objectives.<br />
<br />
== More Info ==<br />
To know more about the project, refer to our [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/edit# project manifesto] or read about our [https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit#slide=id.g98573dba11_0_10 pilot project].<br />
<br />
== Point of Contact ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
== Want to be a part of our community? ==<br />
If you wish to be a part of this challenging glossary management project, then please reach out to us through our mailing list or our slack channel:<br />
* Try setting up your own glossary using the tools and processes we are establishing. Help us improve the process.<br />
* Help research and then document best practices in glossary management.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
<br />
== Code of Conduct ==<br />
We are respectful to each other, and welcoming, in line with [https://www.osgeo.org/code_of_conduct/ | OSGeo's Code of Conduct] policies.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021&diff=126380Season Of Docs 20212021-03-27T00:44:18Z<p>Wiki-Camerons: about osgeo</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= OSGeo's Season of Docs 2021 home page =<br />
<br />
== Proposal ==<br />
OSGeo's Season of Docs [[Season_Of_Docs_2021_Proposal|detailed proposal]] is to build guides and processes for cross-organizational glossaries, focusing initially on projects within the Open Source Geospatial Foundation (OSGeo).<br />
<br />
== Background ==<br />
<br />
For 2021, OSGeo's Season of Docs proposal is to help address glossary challenges faced by many of OSGeo's projects.<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
The cross-organizational glossaries project covers software, information schemas and best practice processes required to set up and manage glossaries which have inter-dependencies with other glossaries.<br />
<br />
Our focus is initially on glossaries within the geospatial domain, but problems we solve will be directly applicable to other domains too.<br />
<br />
== Further Information ==<br />
<br />
Supporting project:<br />
* OSGeo's [[Glossary-Project|Glossary Project]].<br />
* Coordinated by OSGeo's [[Lexicon_Committee|Lexicon Committee]]. You can join the committee if you would like to get involved.<br />
<br />
See also:<br />
* Google's [https://developers.google.com/season-of-docs/ Season of Docs] site.<br />
<br />
== About OSGeo ==<br />
<br />
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.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021&diff=126379Season Of Docs 20212021-03-27T00:38:56Z<p>Wiki-Camerons: /* OSGeo's Season of Docs 2021 home page */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= OSGeo's Season of Docs 2021 home page =<br />
<br />
== Proposal ==<br />
OSGeo's Season of Docs [[Season_Of_Docs_2021_Proposal|detailed proposal]] is to build guides and processes for cross-organizational glossaries, focusing initially on projects within the Open Source Geospatial Foundation (OSGeo).<br />
<br />
== Background ==<br />
<br />
For 2021, OSGeo's Season of Docs proposal is to help address glossary challenges faced by many of OSGeo's projects.<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
The cross-organizational glossaries project covers software, information schemas and best practice processes required to set up and manage glossaries which have inter-dependencies with other glossaries.<br />
<br />
Our focus is initially on glossaries within the geospatial domain, but problems we solve will be directly applicable to other domains too.<br />
<br />
== Further Information ==<br />
<br />
Supporting project:<br />
* OSGeo's [[Glossary-Project|Glossary Project]].<br />
* Coordinated by OSGeo's [[Lexicon_Committee|Lexicon Committee]]. You can join the committee if you would like to get involved.<br />
<br />
See also:<br />
** Google's [https://developers.google.com/season-of-docs/ Season of Docs] site.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Glossary-Project&diff=126378Glossary-Project2021-03-26T06:16:19Z<p>Wiki-Camerons: resize images</p>
<hr />
<div>The OSGeo glossary project is building processes and tools for setting up cross-domain, inter-operable glossaries. The focus is initially on OSGeo and spatial projects, but the patterns will be equally applicable and usable within other domains as well.<br />
<br />
== Goals ==<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when trying to inherit terms from other organizations. The collaborative overhead becomes overwhelming. Communities struggle to agree upon:<br />
* Term definitions,<br />
* Field and sentence structure,<br />
* Tooling,<br />
* Governance, and more. <br />
<br />
== Challenges ==<br />
Here we cover some of the key challenges we’ve been working through.<br />
=== Sharing Terms ===<br />
We’ve been working on how to share terms between glossaries.<br />
<br />
[[File:Sharing terms.png|400px|alt=Sharing terms between organizations]]<br />
<br />
=== Information Schemas ===<br />
We’ve been establishing standardized information structures.<br />
<br />
[[File:Information schema.png|400px|alt=Glossary schema elements]]<br />
<br />
=== Governance ===<br />
We’ve been working on governance models that projects can adopt.<br />
<br />
[[File:Governance real.png|600px|alt=Glossary governance processes]]<br />
<br />
=== Open-source software tooling ===<br />
For building better cross-organizational glossaries, we are using [https://www.glossarist.org/ Glossarist]: an open-source tool to create, maintain, and update glossaries hassle-free. Glossarist is already in use by the ISO/TC 211 spatial standards body. <br />
=== OSGeo Terminology ===<br />
We’ve established an initial [https://osgeodev.geolexica.org/ GeoLexica glossary] covering English terminology used within OSGeo.<br />
<br />
== Umbrella project ==<br />
<br />
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.<br />
<br />
Projects include:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].\== License <br />
<br />
==License==<br />
The open source licenses being used by us and these projects for documentation include:<br />
* [https://creativecommons.org/licenses/by/4.0/ CC-By]<br />
* [https://opensource.org/licenses/0BSD Zero BSD]<br />
<br />
== Next Steps ==<br />
In 2021 and onwards, we aim to achieve the following:<br />
* Create best practices in cross-domain glossary management, for adoption by the open-source and technical writing communities.<br />
* Build a community that defines and manages geospatial terms across multiple geospatial projects and communities. <br />
* Set up processes collated in explanations and how-tos which are easy-to-follow by everyday people wanting to stand up an interoperable glossary.<br />
<br />
We have applied to [https://wiki.osgeo.org/wiki/Season_Of_Docs_2021_Proposal Google Season of Docs 2021] which would help with achieving these objectives.<br />
<br />
== More Info ==<br />
To know more about the project, refer to our [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/edit# project manifesto] or read about our [https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit#slide=id.g98573dba11_0_10 pilot project].<br />
<br />
== Point of Contact ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
== Want to be a part of our community? ==<br />
If you wish to be a part of this challenging glossary management project, then please reach out to us through our mailing list or our slack channel:<br />
* Try setting up your own glossary using the tools and processes we are establishing. Help us improve the process.<br />
* Help research and then document best practices in glossary management.<br />
* Help with whatever dirty work is required to keep the project moving forward.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021&diff=126377Season Of Docs 20212021-03-26T06:07:00Z<p>Wiki-Camerons: /* OSGeo's Season of Docs 2021 home page */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= OSGeo's Season of Docs 2021 home page =<br />
<br />
* OSGeo's Season of Docs proposal is to support OSGeo's [[Glossary-Project|Glossary Project]].<br />
** The project is coordinated by OSGeo's [[Lexicon_Committee|Lexicon Committee]]. You can join the committee if you would like to get involved.<br />
* See also:<br />
** OSGeo's Season of Docs [[Season_Of_Docs_2021_Proposal|Proposal]].<br />
** Google's [https://developers.google.com/season-of-docs/ Season of Docs] site.<br />
<br />
== Background ==<br />
<br />
For 2021, OSGeo's Season of Docs proposal is to help address glossary challenges faced by many of OSGeo's projects.<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
Our focus is initially on glossaries within the geospatial domain, but problems we solve will be directly applicable to other domains too.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021&diff=126376Season Of Docs 20212021-03-26T05:58:00Z<p>Wiki-Camerons: /* OSGeo's Season of Docs 2021 home page */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= OSGeo's Season of Docs 2021 home page =<br />
<br />
* OSGeo's Season of Docs [[Season_Of_Docs_2021_Proposal|Proposal]].<br />
* This year's proposal is being coordinated by OSGeo's [[Lexicon_Committee|Lexicon Committee]]. You can join the committee if you would like to get involved.<br />
* Google's [https://developers.google.com/season-of-docs/ Season of Docs] site provides more details about the broader Season of Docs initiative.<br />
<br />
== Background ==<br />
<br />
For 2021, OSGeo's Season of Docs proposal is to help address glossary challenges faced by many of OSGeo's projects.<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
Our focus is initially on glossaries within the geospatial domain, but problems we solve will be directly applicable to other domains too.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs&diff=126375Season Of Docs2021-03-26T05:57:37Z<p>Wiki-Camerons: season of docs 2021</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
== Welcome to OSGeo's [https://developers.google.com/season-of-docs/ Season of Docs] page ==<br />
<br />
* [[Season_Of_Docs_2019|OSGeo Season of Docs 2019]].<br />
* [[Season_Of_Docs_2021|OSGeo Season of Docs 2021]].<br />
** [[Season_Of_Docs_2021_Proposal|OSGeo Season of Docs 2021 Proposal]].</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021&diff=126374Season Of Docs 20212021-03-26T05:53:01Z<p>Wiki-Camerons: Trim to jump page info</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= OSGeo's Season of Docs 2021 home page =<br />
<br />
* OSGeo's Season of Docs [[Season_Of_Docs_2021_Proposal|Proposal]].<br />
* This year's proposal is being coordinated by OSGeo's [[Lexicon_Committee|Lexicon Committee]]. You can join the committee if you would like to get involved.<br />
* Google's [https://developers.google.com/season-of-docs/ Season of Docs] site provides more details about the broader Season of Docs initiative.<br />
<br />
== Background ==<br />
<br />
For 2021, OSGeo's Season of Docs proposal is to help address glossary challenges faced by many of OSGeo's projects.<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
Our focus is initially on glossaries within the geospatial domain, but problems we solve will be directly applicable to other domains too.<br />
<br />
[[Category:Season of Docs]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021&diff=126373Season Of Docs 20212021-03-26T04:36:36Z<p>Wiki-Camerons: Initial version, based on our proposal. Still to trim this down.</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The [https://wiki.osgeo.org/wiki/Glossary-Project OSGeo Glossary Project] is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is used for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Convenor of the ISO/TC 211 Terminology Management Group (TMG)<br />
* Coordinator of the ISO/TC 211 Multi-Lingual Glossary of Terms (MLGT)<br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care?<br />
** What should you care about?<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
Note: Due to the unknowns in this project, the tech writer and mentors may agree to adjust the scope by mutual written agreement.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Glossary-Project&diff=126370Glossary-Project2021-03-24T19:27:38Z<p>Wiki-Camerons: /* Next Steps */</p>
<hr />
<div>The OSGeo glossary project is building processes and tools for setting up cross-domain, inter-operable glossaries. The focus is initially on OSGeo and spatial projects, but the patterns will be equally applicable and usable within other domains as well.<br />
<br />
== Goals ==<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when trying to inherit terms from other organizations. The collaborative overhead becomes overwhelming. Communities struggle to agree upon:<br />
* Term definitions,<br />
* Field and sentence structure,<br />
* Tooling,<br />
* Governance, and more. <br />
<br />
== Challenges ==<br />
Here we cover some of the key challenges we’ve been working through.<br />
=== Sharing Terms ===<br />
We’ve been working on how to share terms between glossaries.<br />
[[File:Sharing terms.png|thumb]]<br />
=== Information Schemas ===<br />
We’ve been establishing standardized information structures.<br />
[[File:Information schema.png|thumb]]<br />
=== Governance ===<br />
We’ve been working on governance models that projects can adopt.<br />
[[File:Governance real.png|thumb]]<br />
=== Open-source software tooling ===<br />
For building better cross-organizational glossaries, we are using [https://www.glossarist.org/ Glossarist]: an open-source tool to create, maintain, and update glossaries hassle-free. Glossarist is already in use by the ISO/TC 211 spatial standards body. <br />
=== OSGeo Terminology ===<br />
We’ve established an initial [https://osgeodev.geolexica.org/ GeoLexica glossary] covering English terminology used within OSGeo. <br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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. <br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Umbrella project ==<br />
<br />
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.<br />
<br />
Projects include:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].\== License <br />
<br />
==License==<br />
The open source licenses being used by us and these projects for documentation include:<br />
* [https://creativecommons.org/licenses/by/4.0/ CC-By]<br />
* [https://opensource.org/licenses/0BSD Zero BSD]<br />
<br />
== Next Steps ==<br />
In 2021 and onwards, we aim to achieve the following:<br />
* Create best practices in cross-domain glossary management, for adoption by the open-source and technical writing communities.<br />
* Build a community that defines and manages geospatial terms across multiple geospatial projects and communities. <br />
* Set up processes collated in explanations and how-tos which are easy-to-follow by everyday people wanting to stand up an interoperable glossary.<br />
<br />
We have applied to [https://wiki.osgeo.org/wiki/Season_Of_Docs_2021_Proposal Google Season of Docs 2021] which would help with achieving these objectives.<br />
<br />
== More Info ==<br />
To know more about the project, refer to our [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/edit# project manifesto] or read about our [https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit#slide=id.g98573dba11_0_10 pilot project].<br />
<br />
== Point of Contact ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
== Want to be a part of our community? ==<br />
If you wish to be a part of this challenging glossary management project, then please reach out to us through our mailing list or our slack channel:<br />
* Try setting up your own glossary using the tools and processes we are establishing. Help us improve the process.<br />
* Help research and then document best practices in glossary management.<br />
* Help with whatever dirty work is required to keep the project moving forward.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Glossary-Project&diff=126369Glossary-Project2021-03-24T19:19:29Z<p>Wiki-Camerons: /* Next Steps */</p>
<hr />
<div>The OSGeo glossary project is building processes and tools for setting up cross-domain, inter-operable glossaries. The focus is initially on OSGeo and spatial projects, but the patterns will be equally applicable and usable within other domains as well.<br />
<br />
== Goals ==<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when trying to inherit terms from other organizations. The collaborative overhead becomes overwhelming. Communities struggle to agree upon:<br />
* Term definitions,<br />
* Field and sentence structure,<br />
* Tooling,<br />
* Governance, and more. <br />
<br />
== Challenges ==<br />
Here we cover some of the key challenges we’ve been working through.<br />
=== Sharing Terms ===<br />
We’ve been working on how to share terms between glossaries.<br />
[[File:Sharing terms.png|thumb]]<br />
=== Information Schemas ===<br />
We’ve been establishing standardized information structures.<br />
[[File:Information schema.png|thumb]]<br />
=== Governance ===<br />
We’ve been working on governance models that projects can adopt.<br />
[[File:Governance real.png|thumb]]<br />
=== Open-source software tooling ===<br />
For building better cross-organizational glossaries, we are using [https://www.glossarist.org/ Glossarist]: an open-source tool to create, maintain, and update glossaries hassle-free. Glossarist is already in use by the ISO/TC 211 spatial standards body. <br />
=== OSGeo Terminology ===<br />
We’ve established an initial [https://osgeodev.geolexica.org/ GeoLexica glossary] covering English terminology used within OSGeo. <br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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. <br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Next Steps ==<br />
In 2021 and onwards, we aim to achieve the following:<br />
* Create best practices in cross-domain glossary management, for adoption by the open-source and technical writing communities.<br />
* Build a community that defines and manages geospatial terms across multiple geospatial projects and communities. <br />
* Set up processes collated in explanations and how-tos which are easy-to-follow by everyday people wanting to stand up an interoperable glossary.<br />
<br />
We have applied to [https://wiki.osgeo.org/wiki/Season_Of_Docs_2021_Proposal Google Season of Docs 2021] which would help with achieving these objectives.<br />
<br />
== More Info ==<br />
To know more about the project, refer to our [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/edit# project manifesto] or read about our [https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit#slide=id.g98573dba11_0_10 pilot project].<br />
<br />
== Point of Contact ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
== Want to be a part of our community? ==<br />
If you wish to be a part of this challenging glossary management project, then please reach out to us through our mailing list or our slack channel:<br />
* Try setting up your own glossary using the tools and processes we are establishing. Help us improve the process.<br />
* Help research and then document best practices in glossary management.<br />
* Help with whatever dirty work is required to keep the project moving forward.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126363Season Of Docs 2021 Proposal2021-03-24T09:15:13Z<p>Wiki-Camerons: fixed one url</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The [https://wiki.osgeo.org/wiki/Glossary-Project OSGeo Glossary Project] is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is used for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Convenor of the ISO/TC 211 Terminology Management Group (TMG)<br />
* Coordinator of the ISO/TC 211 Multi-Lingual Glossary of Terms (MLGT)<br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care?<br />
** What should you care about?<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
Note: Due to the unknowns in this project, the tech writer and mentors may agree to adjust the scope by mutual written agreement.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Glossary-Project&diff=126360Glossary-Project2021-03-23T22:33:23Z<p>Wiki-Camerons: /* Want to be a part of our community? */</p>
<hr />
<div>The OSGeo glossary project is building processes and tools for setting up cross-domain, inter-operable glossaries. The focus is initially on OSGeo and spatial projects, but the patterns will be equally applicable and usable within other domains as well.<br />
<br />
== Goals ==<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when trying to inherit terms from other organizations. The collaborative overhead becomes overwhelming. Communities struggle to agree upon:<br />
* Term definitions,<br />
* Field and sentence structure,<br />
* Tooling,<br />
* Governance, and more. <br />
<br />
== Challenges ==<br />
Here we cover some of the key challenges we’ve been working through.<br />
=== Sharing Terms ===<br />
We’ve been working on how to share terms between glossaries.<br />
[[File:Sharing terms.png|thumb]]<br />
=== Information Schemas ===<br />
We’ve been establishing standardized information structures.<br />
[[File:Information schema.png|thumb]]<br />
=== Governance ===<br />
We’ve been working on governance models that projects can adopt.<br />
[[File:Governance real.png|thumb]]<br />
=== Open-source software tooling ===<br />
For building better cross-organizational glossaries, we are using [https://www.glossarist.org/ Glossarist]: an open-source tool to create, maintain, and update glossaries hassle-free. Glossarist is already in use by the ISO/TC 211 spatial standards body. <br />
=== OSGeo Terminology ===<br />
We’ve established an initial [https://osgeodev.geolexica.org/ GeoLexica glossary] covering English terminology used within OSGeo. <br />
<br />
== Next Steps ==<br />
In 2021 and onwards, we aim to achieve the following:<br />
* Create best practices in cross-domain glossary management, for adoption by the open-source and technical writing communities.<br />
* Build a community that defines and manages geospatial terms across multiple geospatial projects and communities. <br />
* Set up processes collated in explanations and how-tos which are easy-to-follow by everyday people wanting to stand up an interoperable glossary.<br />
<br />
== More Info ==<br />
To know more about the project, refer to our [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/edit# project manifesto] or read about our [https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit#slide=id.g98573dba11_0_10 pilot project].<br />
<br />
== Point of Contact ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
== Want to be a part of our community? ==<br />
If you wish to be a part of this challenging glossary management project, then please reach out to us through our mailing list or our slack channel:<br />
* Try setting up your own glossary using the tools and processes we are establishing. Help us improve the process.<br />
* Help research and then document best practices in glossary management.<br />
* Help with whatever dirty work is required to keep the project moving forward.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126353Season Of Docs 2021 Proposal2021-03-23T10:06:23Z<p>Wiki-Camerons: /* Mentors */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The [OSGeo Glossary Project](https://wiki.osgeo.org/wiki/Glossary_Project) is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is used for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Convenor of the ISO/TC 211 Terminology Management Group (TMG)<br />
* Coordinator of the ISO/TC 211 Multi-Lingual Glossary of Terms (MLGT)<br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care?<br />
** What should you care about?<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
Note: Due to the unknowns in this project, the tech writer and mentors may agree to adjust the scope by mutual written agreement.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126352Season Of Docs 2021 Proposal2021-03-23T10:05:08Z<p>Wiki-Camerons: /* Backing organizations */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The [OSGeo Glossary Project](https://wiki.osgeo.org/wiki/Glossary_Project) is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is used for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Convenor of the ISO/TC 211 Terminology Management Group (TMG)<br />
* Coordinator of the ISO/TC 211 Multi-Lingual Glossary of Terms (MLGT)<br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care?<br />
** What should you care about?<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
Note: Due to the unknowns in this project, the tech writer and mentors may agree to adjust the scope by mutual written agreement.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126351Season Of Docs 2021 Proposal2021-03-23T09:45:56Z<p>Wiki-Camerons: /* Cross-organizational glossaries project */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when attempting to share partial or dated term lists between organizations.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Convenor of the ISO/TC 211 Terminology Management Group (TMG)<br />
* Coordinator of the ISO/TC 211 Multi-Lingual Glossary of Terms (MLGT)<br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care?<br />
** What should you care about?<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
Note: Due to the unknowns in this project, the tech writer and mentors may agree to adjust the scope by mutual written agreement.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=User_talk:Farnaz_rahmani&diff=126350User talk:Farnaz rahmani2021-03-23T09:02:31Z<p>Wiki-Camerons: Welcome!</p>
<hr />
<div>'''Welcome to ''OSGeo''!'''<br />
We hope you will contribute much and well.<br />
You will probably want to read the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents help pages].<br />
Again, welcome and have fun! [[User:Camerons|Camerons]] ([[User talk:Camerons|talk]]) 02:02, 23 March 2021 (PDT)</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=User:Farnaz_rahmani&diff=126349User:Farnaz rahmani2021-03-23T09:02:31Z<p>Wiki-Camerons: Creating user page for new user.</p>
<hr />
<div>I am an enthusiastic expert on learning and training qgis software .</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=User_talk:Ankitatripathi&diff=126348User talk:Ankitatripathi2021-03-23T08:59:31Z<p>Wiki-Camerons: Welcome!</p>
<hr />
<div>'''Welcome to ''OSGeo''!'''<br />
We hope you will contribute much and well.<br />
You will probably want to read the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents help pages].<br />
Again, welcome and have fun! [[User:Camerons|Camerons]] ([[User talk:Camerons|talk]]) 01:59, 23 March 2021 (PDT)</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=User:Ankitatripathi&diff=126347User:Ankitatripathi2021-03-23T08:59:30Z<p>Wiki-Camerons: Creating user page for new user.</p>
<hr />
<div>Technical Writer and working toward creating a glossary for OSGeo terms for season of docs 2021</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126333Season Of Docs 2021 Proposal2021-03-21T00:00:35Z<p>Wiki-Camerons: /* In scope */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Primary author of the ISO/TC 211 Terminology Management Group’s glossary<br />
* <br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care?<br />
** What should you care about?<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
Note: Due to the unknowns in this project, the tech writer and mentors may agree to adjust the scope by mutual written agreement.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126332Season Of Docs 2021 Proposal2021-03-20T23:54:51Z<p>Wiki-Camerons: /* In scope */</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Primary author of the ISO/TC 211 Terminology Management Group’s glossary<br />
* <br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care?<br />
** What should you care about?<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126331Season Of Docs 2021 Proposal2021-03-20T23:51:36Z<p>Wiki-Camerons: add logos</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Primary author of the ISO/TC 211 Terminology Management Group’s glossary<br />
* <br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care.<br />
** What should you care about.<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126330Season Of Docs 2021 Proposal2021-03-20T23:14:14Z<p>Wiki-Camerons: /* Potential tech writers */</p>
<hr />
<div>= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Primary author of the ISO/TC 211 Terminology Management Group’s glossary<br />
* <br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care.<br />
** What should you care about.<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* She has been actively involved with OSGeo communities, the cross-organizational glossary project and The Good Docs Project on a volunteer basis, and has a strong background understanding of the problem.<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126329Season Of Docs 2021 Proposal2021-03-20T22:56:48Z<p>Wiki-Camerons: /* OSGeo Season of Docs proposal */</p>
<hr />
<div>= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Primary author of the ISO/TC 211 Terminology Management Group’s glossary<br />
* <br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care.<br />
** What should you care about.<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* 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<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126328Season Of Docs 2021 Proposal2021-03-20T22:53:48Z<p>Wiki-Camerons: /* Project budget */</p>
<hr />
<div>= OSGeo Season of Docs proposal =<br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Primary author of the ISO/TC 211 Terminology Management Group’s glossary<br />
* <br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care.<br />
** What should you care about.<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* 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<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
{| class="wikitable"<br />
|-<br />
! Item !! Amount $US !! Notes<br />
|-<br />
| Technical writer || 4,500 || <br />
|-<br />
| Supporting organization overheads || 300 || Incidentals such as bank processing fees, and general good will.<br />
|-<br />
| 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.<br />
|-<br />
| Total || 5,000 || <br />
|}<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs_2021_Proposal&diff=126327Season Of Docs 2021 Proposal2021-03-20T22:48:12Z<p>Wiki-Camerons: Proposal sourced from https://docs.google.com/document/d/1enUFAZX1srNmZ3oy4rt_gqv8AeCx2tL5bM6ej8kq9N4/edit</p>
<hr />
<div>= OSGeo Season of Docs proposal =<br />
<br />
= Cross-organizational glossaries guide - OSGeo Foundation =<br />
<br />
This is a proposal to have a technical writer sponsored under [https://developers.google.com/season-of-docs Google’s Season of Docs] to:<br />
<br />
* Document processes for establishing cross-organizational glossaries.<br />
* Support others set up pilot glossaries within some of the geospatial open source projects.<br />
<br />
== About OSGeo ==<br />
<br />
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.<br />
<br />
== Cross-organizational glossaries project ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
It is initially focusing on glossaries within the geospatial domain, where most of our volunteers are actively involved.<br />
<br />
=== Backing organizations ===<br />
<br />
The project is jointly backed by volunteers from multiple organizations:<br />
<br />
* The [https://osgeo.org Open Source Geospatial (OSGeo) Foundation]<br />
** An umbrella foundation, representing 50+ geospatial open source projects, sub-committees, and local chapters.<br />
** The OSGeo Foundation is heading this Season of Docs proposal.<br />
* [https://thegooddocsproject.dev The Good Docs Project]<br />
** An open source community of technical writers building best practice templates and writing instructions for documenting open source software.<br />
** A best practices glossary template and how-to guide is to be developed as part of this project.<br />
* The [https://www.glossarist.org/ Glossarist] open source project<br />
** A project dedicated to standing up and managing standards based, interoperable glossaries.<br />
** This software is for government sized glossaries and is based on best practice standards.<br />
** This software is being used within the project.<br />
* The [https://www.ogc.org/ Open Geospatial Consortium (OGC)]<br />
** An international geospatial standards setting body.<br />
** The OGC volunteers have decades of experience with lexicon standards and terminology management which they are contributing to the project.<br />
* [https://committee.iso.org/home/tc211 The ISO/TC211 geospatial standards committee]<br />
** A committee managing geospatial glossary terminology.<br />
** This committee is providing terminology, and mentoring in managing terminology.<br />
<br />
=== Mentors ===<br />
<br />
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.<br />
<br />
Ilie Codrina Maria<br />
<br />
* OSGeo Foundation board member<br />
<br />
Nikos Lambrinos<br />
<br />
* Geography Professor<br />
* Chief Editor of GeoForAll Newsletter and GeoForAll glossary<br />
* (GeoForAll is an initiative under the OSGeo Foundation)<br />
<br />
Cameron Shorter<br />
<br />
* One of the coordinators of The Good Docs Project<br />
* Ex OSGeo board member, and open source project coordinator/contributor<br />
* Tech writer at Google<br />
<br />
Rob Atkinson<br />
<br />
* Expert on structured data, schemas, glossaries, interoperability, …<br />
* Open Geospatial Consortium staff member<br />
<br />
Ronald Tse<br />
<br />
* Lead developer of the open source glossarist software being used<br />
* ISO/TC 211 and OGC member<br />
<br />
Reese Plews<br />
<br />
* Primary author of the ISO/TC 211 Terminology Management Group’s glossary<br />
* <br />
<br />
Ankita Tripathi (if not engaged as the tech writer for this project)<br />
<br />
* Technical Writer<br />
* Project Steering Committee member of The Good Docs Project<br />
<br />
=== Umbrella project ===<br />
<br />
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.<br />
<br />
For evidence of a mature and active community, refer to:<br />
<br />
* [https://osgeo.geolexica.org/concepts/ Geospatial glossary terms], compiled by our team.<br />
* [https://github.com/thegooddocsproject/templates The Good Docs Project templates repository], where the glossary template will fit.<br />
* [https://github.com/OSGeo/OSGeoLive-doc Docs repository for the OSGeo-Live] distribution, where we intend to add glossary entries.<br />
* [https://github.com/glossarist Glossarist github repository], which stores the glossary software.<br />
* [https://docs.google.com/document/d/1yzncnQB7uYktPnAQ4DqZYVPDdYnqDrWmqHzcpXrjkPg/edit Minutes from weekly meetings].<br />
<br />
== Season of Docs focus ==<br />
<br />
From the perspective of projects under the umbrella of the OSGeo Foundation’s perspective:<br />
<br />
* 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.<br />
<br />
From our cross-organisational glossary’s project perspective:<br />
<br />
* 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.<br />
<br />
The focus of this Season of Docs initiative is to engage a technical writer to develop such documentation, and test it with pilot users.<br />
<br />
=== Season of Docs scope ===<br />
<br />
==== In scope ====<br />
<br />
Deliverable: Cross-organizational glossaries concept document<br />
<br />
* This document will explain concepts and theory behind cross-organizational glossaries. It will potentially cover topics such as:<br />
** Why you should care.<br />
** When you should care.<br />
** What should you care about.<br />
** Options and recommendations for information schemas.<br />
** Options and recommendations for governance.<br />
** Relevant standards.<br />
** References to further research.<br />
<br />
Deliverable: glossary-template and glossary-template-guide<br />
<br />
* 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.<br />
<br />
Deliverable: Support pilot projects testing the documentation<br />
<br />
* The tech writer will participate in discussions with people testing the templates and concept documentation, provide advice, and absorb feedback.<br />
* This deliverable is dependent upon the project sourcing appropriate volunteers within the timeframe of the project.<br />
<br />
Deliverable: Project Case Study<br />
<br />
* 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.<br />
* This case study will be co-authored by the project mentors, and interested community mentors.<br />
<br />
==== Source material ====<br />
<br />
Source material is to be collated from existing team material and know-how.<br />
<br />
==== Quality ====<br />
<br />
As this project is breaking a significant amount of new ground, we don’t expect to get it right the first time.<br />
<br />
We anticipate the resulting documentation to be of pilot quality. It is likely to contain placeholders and sections to be filled in later.<br />
<br />
==== Out of scope ====<br />
<br />
* Installing or configuring specific glossaries. This will be the responsibility of participating projects.<br />
* Contributing to the term definitions within specific glossaries. This will be the responsibility of glossary owners.<br />
* Establishing governance processes for a specific glossary.<br />
* Establishing a measurement framework for the success of this project.<br />
<br />
==== Potential tech writers ====<br />
<br />
We have a tech writer, Ankita Tripathi, who we would like to engage for this project.<br />
<br />
* Ankita is a professional technical writer.<br />
* 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<br />
* She has shown significant competence, initiative and dedication as an open source technical writer, and will be well positioned to tackle this project.<br />
<br />
If Ankita’s availability changes, there are others in our community we could approach.<br />
<br />
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.<br />
<br />
=== Measuring Season of Docs success ===<br />
<br />
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).<br />
<br />
Goal: Help communicators reduce cognitive load<br />
<br />
Sub-goal: Help communicators build and manage glossaries which explain terms used by the communitators<br />
<br />
Sub-goal: Provide a scalable framework for cross-organizational glossary management<br />
<br />
Sub-goal: Reduce effort required for cross-organizational glossary management<br />
<br />
* Indicator: Projects stand up standards compliant glossary services<br />
** Measure: Count the number of standards compliant glossary services stood up based on our instructions, that we are aware of.<br />
*** 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.<br />
<br />
Sub-goal: Educate people on the benefits and challenges of cross-organizational glossary management<br />
<br />
* Indicator: Explanation document is read<br />
** Metric: Count the views of an explanation document<br />
*** Success criteria: Within the project timeframe, we don’t expect to have collected enough page views to gain any meaningful results.<br />
<br />
== Project budget ==<br />
<br />
== Additional information ==<br />
<br />
* 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.<br />
* Some of our mentors and participating community members are professional technical writers.<br />
* 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.<br />
<br />
We believe that this depth of experience provides us with insights, experience, and the drive required to tackle this difficult documentation use case.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs&diff=126326Season Of Docs2021-03-20T21:59:51Z<p>Wiki-Camerons: fix link</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
== Welcome to OSGeo's [https://developers.google.com/season-of-docs/ Season of Docs] page ==<br />
<br />
* [[Season_Of_Docs_2019|OSGeo Season of Docs 2019]].<br />
* [[Season_Of_Docs_2021_Proposal|OSGeo Season of Docs 2021]].<br />
<br />
[[Category:Season of Docs]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_Of_Docs&diff=126325Season Of Docs2021-03-20T21:54:21Z<p>Wiki-Camerons: Jump page</p>
<hr />
<div><center><br />
[[Image:SeasonofDocs_Logo_SecondaryGrey_300ppi.png|400px|link=https://developers.google.com/season-of-docs/]] <font size="+3"> @ </font> <br />
[[Image:Osgeo-logo.png|300px|link=http://www.osgeo.org]]<br />
</center><br />
<br />
== Welcome to OSGeo's [https://developers.google.com/season-of-docs/ Season of Docs] page ==<br />
<br />
* [[Season_Of_Docs_2019|OSGeo Season of Docs 2019]].<br />
* [[Season_Of_Docs_2019|OSGeo Season of Docs 2021]].<br />
<br />
[[Category:Season of Docs]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=125321Lexicon Committee2020-09-09T03:00:00Z<p>Wiki-Camerons: /* Committee members */ Felicity requested to be moved to past members</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeodev.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Projects ==<br />
* [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/ Cross domain glossary management]<br />
<br />
== Resources ==<br />
* [https://osgeodev.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]], chair (OSGeoLive, The Good Docs Project)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* Alyssa Rock, technical writer and contributor to The Good Docs Project<br />
* Ankita Tripathi, Technical Writer and Contributor to The Good Docs Project<br />
* Naini Khajanchi, Technical Compliance Writer<br />
* Nikos Lambrinos, Geography Professor, Chief Editor of GeoForAll Newsletter, founder of the Hellenic digital earth Centre of Excellence<br />
* Erik Stubkjær, co-editor of the Cadastre and Land Administration Thesaurus (CaLAThe)<br />
* [[User:Brandonnodnarb|Brandon Whitehead]], Environmental Data Scientist, Manaaki Whenua – Landcare Research<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
* Felicity Brand, technical writer and Contributor to The Good Docs Project<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=125316Lexicon Committee2020-09-09T01:53:26Z<p>Wiki-Camerons: /* Committee members */ Updated member list and selected a chair based on positive and no negative votes on list</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeodev.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Projects ==<br />
* [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/ Cross domain glossary management]<br />
<br />
== Resources ==<br />
* [https://osgeodev.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]], chair (OSGeoLive, The Good Docs Project)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* Alyssa Rock, technical writer and contributor to The Good Docs Project<br />
* Ankita Tripathi, Technical Writer and Contributor to The Good Docs Project<br />
* Naini Khajanchi, Technical Compliance Writer<br />
* Nikos Lambrinos, Geography Professor, Chief Editor of GeoForAll Newsletter, founder of the Hellenic digital earth Centre of Excellence<br />
* Erik Stubkjær, co-editor of the Cadastre and Land Administration Thesaurus (CaLAThe)<br />
* Brandon Whitehead, Environmental Data Scientist, Manaaki Whenua – Landcare Research<br />
* Felicity Brand, technical writer and Contributor to The Good Docs Project<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=125311Lexicon Committee2020-09-07T11:18:02Z<p>Wiki-Camerons: /* Committee members */ Jorge has moved to Past Members</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeodev.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Projects ==<br />
* [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/ Cross domain glossary management]<br />
<br />
== Resources ==<br />
* [https://osgeodev.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]] (OSGeoLive, The Good Docs Project)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=125194Lexicon Committee2020-08-16T12:41:27Z<p>Wiki-Camerons: /* Communication */</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeodev.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list]. (Note: After subscribing, check your email spam for your subscription confirmation email. It is sent straight after subscribing. Or ask cameron . shorter AT gmail .com for help.)<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Projects ==<br />
* [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/ Cross domain glossary management]<br />
<br />
== Resources ==<br />
* [https://osgeodev.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]] (OSGeoLive, The Good Docs Project)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=125177Lexicon Committee2020-08-11T02:43:54Z<p>Wiki-Camerons: Projects.</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeodev.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list].<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Projects ==<br />
* [https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/ Cross domain glossary management]<br />
<br />
== Resources ==<br />
* [https://osgeodev.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]] (OSGeoLive, The Good Docs Project)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=125002Lexicon Committee2020-07-07T19:15:57Z<p>Wiki-Camerons: /* Committee members */</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeodev.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list].<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Resources ==<br />
* [https://osgeodev.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]] (OSGeoLive, The Good Docs Project)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=124636Lexicon Committee2020-06-06T03:59:50Z<p>Wiki-Camerons: Added resources links</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeo.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on [Open Source https://github.com/geolexica/osgeo.geolexica.org] (which mitigates project risk). <br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
* Mail List: We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list].<br />
* Meetings<br />
** Telecon 1: 2020-03-06 [https://drive.google.com/open?id=1JdvCmmOJWdZgch0AdVG1YSEQ8J9Oq_Jy Minutes]<br />
<br />
== Resources ==<br />
* [https://osgeo.geolexica.org/ Geolexia glossary]<br />
* [https://github.com/geolexica/osgeo.geolexica.org Open Source software behind Geolexia]<br />
* [https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit# Draft term structure and process]<br />
* [https://docs.google.com/spreadsheets/d/1nFOa7qE309C6rbnhJXd0EjUKEiqCDYvgpCJpyTjbhmo/edit#gid=222410614 Terms spreadsheet]<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]] (OSGeoLive, WriteTheDocs)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
* [[User:Codrina|Ilie Codrina Maria]] (OSGeo)<br />
* [[User:Peter_Loewe|Peter Löwe]] (OSGeo/GRASS/RDA/EGU-ESSI)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_of_Docs_Lessons_Learned_2019&diff=123139Season of Docs Lessons Learned 20192020-01-26T01:34:24Z<p>Wiki-Camerons: /* Finding motivated contributors */</p>
<hr />
<div>[[Season_Of_Docs_2019|Season of Docs]] home page.<br />
A collation of lessons that we have learned while participating in the 2019 Season of Docs.<br />
<br />
=Organisation Application Process=<br />
==Define "Technical Writer"==<br />
When I was talking about Season Of Docs with developers and writers we often lacked a common understanding of a technical writer's role. Many focused on the simpler and most immediate problems faced. In it's broadest sense, almost anyone involved in a software project is a technical writer:<br />
* The developer who comments their code.<br />
* The user or support person answering getting started questions within a community forum.<br />
* The marketer describing the product's features.<br />
So I started using the term "Senior Technical Writer" to focus conversations on harder writing problems, such as strategy and information architecture.<br />
<br />
While everyone wants good documentation, I found that few share a clear definition of what it looks like, and fewer agree on tasks required to achieve this. The Season of Docs provided a list of [https://developers.google.com/season-of-docs/docs/project-ideas Example Projects] which helped, but I think it would useful to define technical writer roles more clearly, describing:<br />
* The value technical writers can bring to a project,<br />
* The skills they bring, <br />
* The roles they can fill,<br />
* And what writers need from developers to collectively become more effective.<br />
<br />
==Expand technical writing roles==<br />
Some common themes emerged when talking with our OSGeo projects about needs for documentation. We focused on tasks requiring high order writing skills, which are harder to find within open source communities. However, there are plenty of other important roles which are also needed. Future Season of Docs initiatives could extend the breadth of roles supported.<br />
* Triaging a documentation issue tracker was typically under-resourced. It is hard to find volunteers for non-glamourous, time-consuming roles like this. And while it isn't specifically a tech writing role, it is important for the success of a tech writing program.<br />
* We found plenty of project users who wouldn't identify as technical writers, who would like to give back to their open source community through documentation. This year's OSGeo Season of Docs tasks has focused on empowering these users to contribute to documentation.<br />
* Community building and community support is a valuable way to attract project contributions to a project, be that via documentation, code, or something else. This outreach role is a valuable role worth fostering. <br />
* Much of our documentation is written by developers using poor language choice. English documentation is often written by non-native English speakers. Future initiatives could support junior writers reviewing documentation against a specific style guide.<br />
* Many writers are not technical. They are unfamiliar with wiki formatting, git, and publishing pipelines. If we can simplify tools we will increase the pool of writers willing to contribute to our projects. (This might be a focus area for Google Summer of Code.)<br />
* Similarly, the documentation management and publishing infrastructure need to be set up and maintained. It is more within a programmer's skill-set than a technical writer's.<br />
<br />
==SeasonOfDocs blog aggregator==<br />
As many of us involved in Season Of Docs are writers, many of us will be blogging about it.<br />
* I see Sarah has: https://ffeathers.wordpress.com/2019/05/02/season-of-docs-is-now-ready-for-tech-writer-exploration/<br />
* Me too: http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html<br />
<br />
I suggest it would be handy to set up a Planet Season Of Docs blog aggregator of people involved. Something like what we have set up at the Open Source Geospatial Foundation for those of us who blog about geospatial topics. https://planet.osgeo.org/<br />
<br />
==Deadline straight after public holiday==<br />
The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.<br />
<br />
=Writer Exploration period=<br />
<br />
== Concise Summary of Project Writing Tasks ==<br />
Season Of Docs provides a list of [https://developers.google.com/season-of-docs/docs/participants/ Participating Organisations], with a summary of the project, links to the pages about tasks, and contact points. This is good, but I'd suggest slight refinements.<br />
* Descriptions of projects cover the project's technology, however, the tech writer is likely more interested in types of writing required and how it matches the writer's skill set.<br />
* I suggest keeping the list of projects concise (and probably encourage the technical description to be more concise, limited to 2 or 3 sentences).<br />
* I suggest each project summarise their requirements from a technical writer.<br />
<br />
== Volunteers welcomed ==<br />
Season of Docs only has space for a few paid writers, but this is an opportunity for projects to attract volunteer tech writers to join. Feedback from one senior tech writer I talked to:<br />
<br />
"I'm interested in Season of Docs, but I'm not in a position to commit to a fixed deliverable due to my work/life commitments, and I haven't seen anywhere I can engage as a volunteer."<br />
<br />
We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.<br />
<br />
== Communication Overload ==<br />
=== FAQ ===<br />
Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.<br />
<br />
=== Project Description Overhead ===<br />
With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects? <br />
# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.<br />
# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.<br />
<br />
=== Applicant Overload ===<br />
We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:<br />
# Ask applicants to respect the time of projects.<br />
# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)<br />
# Are you interested in volunteering, if so, then have a look at this separate list ...<br />
# ...<br />
<br />
== Doc license ==<br />
I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)<br />
<br />
= Development Phase =<br />
== Problems Open Source doc teams face ==<br />
I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.<br />
<br />
* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744<br />
* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html<br />
<br />
There are lessons in here which I think should be absorbed into Season of Docs:<br />
* Docs should start with an information architecture<br />
* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].<br />
* Community leadership is really important. <br />
* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].<br />
[[Category: Season of Docs]]<br />
<br />
==Writing tools don't match writing workflows==<br />
Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.<br />
===git - pros and cons of git===<br />
===wiki markups - pros and cons===<br />
===google docs - pros and cons===<br />
===gitdocs===<br />
gitdocs looks promising. Has anyone tried it and can report back?<br />
<br />
==Missing Measurement tools==<br />
<br />
==Missing templates==<br />
<br />
==Gap Analysis==<br />
<br />
==Missing quality definitions==<br />
<br />
==Glossaries and lexicon management==<br />
<br />
==Finding motivated contributors==<br />
A goal of SeasonOfDocs is to "bring open-source and technical writer communities together, to the benefit of both. Together we raise awareness of open source, of docs, and of technical writing."<br />
To realise this goal, let's consider the motivations of people involved. As explained in Eric S Raymond's first rule of open source in [http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s02.html The Cathedral and the Bazaar]:<br />
<br />
''# Every good work of [open source] software starts by scratching a developer's personal itch.''<br />
<br />
Software developers write great open-source software because they are both competent (as developers) and motivated (with an itch to scratch).<br />
<br />
The challenge we face with open source docs is that it is hard to find people who are competent, have an itch to scratch, and are not faced with a significant barrier to entry (for the person's skill profile).<br />
<br />
===Software users:===<br />
Interest:<br />
* Often are very appreciative of the free software that developers have given them and want to give back in some way.<br />
* Have often been frustrated by poor documentation.<br />
* After finding a solution, are often prepared to write up a specific doc problem.<br />
* Might be prepared to write up a doc section if they feel it would be helpful and appreciated.<br />
<br />
Hindered by:<br />
* Technical ramp-up required to learn to write docs (such as git, wiki markup languages).<br />
* Lack of writing experience, experience with style guides, document structures, etc.<br />
* Lack of understanding of the documentation strategy and what sort of documentation should be written.<br />
* Often don't feel worthy to provide contributions. "Developers know the software better than I.", "I'm not a trained writer."<br />
<br />
===Software developers:===<br />
Disinterest:<br />
* Would prefer to write code.<br />
<br />
Hindered by:<br />
* Lack of writing experience, experience with style guides, document structures, etc.<br />
<br />
Interest:<br />
* Often acknowledge the importance of documentation and would like to see their product as being polished.<br />
* Might be suffering from frustrated user community asking questions because they can't find good docs.<br />
<br />
===Technical Writers===<br />
Disinterest:<br />
* Typically are not users of the open-source application, so haven't used the documentation and haven't experienced a driving itch to fix them.<br />
<br />
Interest Google Season of Docs:<br />
* Have joined Google Season of Docs, maybe wanting to learn about open source, maybe because they are getting paid, maybe because working on a sexy Google project is interesting or would look good on the resume.<br />
<br />
Interest in TheGoodDocsProject:<br />
* We have attracted multiple VOLUNTEER tech writers to help create writing templates as part of [https://thegooddocsproject.dev/ TheGoodDocsProject].<br />
* In this case, tech writers are scratching an itch. The templates they've been motivated to create will help address challenges writers face on a daily basis.<br />
* When shared with open source projects, the templates will remove barriers to entry for project users and developers, opening up the potential contributor base to open-source documentation.<br />
<br />
==Barriers to entry==</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_of_Docs_Lessons_Learned_2019&diff=123138Season of Docs Lessons Learned 20192020-01-26T00:45:07Z<p>Wiki-Camerons: /* Finding motivated contributors */</p>
<hr />
<div>[[Season_Of_Docs_2019|Season of Docs]] home page.<br />
A collation of lessons that we have learned while participating in the 2019 Season of Docs.<br />
<br />
=Organisation Application Process=<br />
==Define "Technical Writer"==<br />
When I was talking about Season Of Docs with developers and writers we often lacked a common understanding of a technical writer's role. Many focused on the simpler and most immediate problems faced. In it's broadest sense, almost anyone involved in a software project is a technical writer:<br />
* The developer who comments their code.<br />
* The user or support person answering getting started questions within a community forum.<br />
* The marketer describing the product's features.<br />
So I started using the term "Senior Technical Writer" to focus conversations on harder writing problems, such as strategy and information architecture.<br />
<br />
While everyone wants good documentation, I found that few share a clear definition of what it looks like, and fewer agree on tasks required to achieve this. The Season of Docs provided a list of [https://developers.google.com/season-of-docs/docs/project-ideas Example Projects] which helped, but I think it would useful to define technical writer roles more clearly, describing:<br />
* The value technical writers can bring to a project,<br />
* The skills they bring, <br />
* The roles they can fill,<br />
* And what writers need from developers to collectively become more effective.<br />
<br />
==Expand technical writing roles==<br />
Some common themes emerged when talking with our OSGeo projects about needs for documentation. We focused on tasks requiring high order writing skills, which are harder to find within open source communities. However, there are plenty of other important roles which are also needed. Future Season of Docs initiatives could extend the breadth of roles supported.<br />
* Triaging a documentation issue tracker was typically under-resourced. It is hard to find volunteers for non-glamourous, time-consuming roles like this. And while it isn't specifically a tech writing role, it is important for the success of a tech writing program.<br />
* We found plenty of project users who wouldn't identify as technical writers, who would like to give back to their open source community through documentation. This year's OSGeo Season of Docs tasks has focused on empowering these users to contribute to documentation.<br />
* Community building and community support is a valuable way to attract project contributions to a project, be that via documentation, code, or something else. This outreach role is a valuable role worth fostering. <br />
* Much of our documentation is written by developers using poor language choice. English documentation is often written by non-native English speakers. Future initiatives could support junior writers reviewing documentation against a specific style guide.<br />
* Many writers are not technical. They are unfamiliar with wiki formatting, git, and publishing pipelines. If we can simplify tools we will increase the pool of writers willing to contribute to our projects. (This might be a focus area for Google Summer of Code.)<br />
* Similarly, the documentation management and publishing infrastructure need to be set up and maintained. It is more within a programmer's skill-set than a technical writer's.<br />
<br />
==SeasonOfDocs blog aggregator==<br />
As many of us involved in Season Of Docs are writers, many of us will be blogging about it.<br />
* I see Sarah has: https://ffeathers.wordpress.com/2019/05/02/season-of-docs-is-now-ready-for-tech-writer-exploration/<br />
* Me too: http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html<br />
<br />
I suggest it would be handy to set up a Planet Season Of Docs blog aggregator of people involved. Something like what we have set up at the Open Source Geospatial Foundation for those of us who blog about geospatial topics. https://planet.osgeo.org/<br />
<br />
==Deadline straight after public holiday==<br />
The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.<br />
<br />
=Writer Exploration period=<br />
<br />
== Concise Summary of Project Writing Tasks ==<br />
Season Of Docs provides a list of [https://developers.google.com/season-of-docs/docs/participants/ Participating Organisations], with a summary of the project, links to the pages about tasks, and contact points. This is good, but I'd suggest slight refinements.<br />
* Descriptions of projects cover the project's technology, however, the tech writer is likely more interested in types of writing required and how it matches the writer's skill set.<br />
* I suggest keeping the list of projects concise (and probably encourage the technical description to be more concise, limited to 2 or 3 sentences).<br />
* I suggest each project summarise their requirements from a technical writer.<br />
<br />
== Volunteers welcomed ==<br />
Season of Docs only has space for a few paid writers, but this is an opportunity for projects to attract volunteer tech writers to join. Feedback from one senior tech writer I talked to:<br />
<br />
"I'm interested in Season of Docs, but I'm not in a position to commit to a fixed deliverable due to my work/life commitments, and I haven't seen anywhere I can engage as a volunteer."<br />
<br />
We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.<br />
<br />
== Communication Overload ==<br />
=== FAQ ===<br />
Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.<br />
<br />
=== Project Description Overhead ===<br />
With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects? <br />
# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.<br />
# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.<br />
<br />
=== Applicant Overload ===<br />
We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:<br />
# Ask applicants to respect the time of projects.<br />
# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)<br />
# Are you interested in volunteering, if so, then have a look at this separate list ...<br />
# ...<br />
<br />
== Doc license ==<br />
I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)<br />
<br />
= Development Phase =<br />
== Problems Open Source doc teams face ==<br />
I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.<br />
<br />
* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744<br />
* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html<br />
<br />
There are lessons in here which I think should be absorbed into Season of Docs:<br />
* Docs should start with an information architecture<br />
* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].<br />
* Community leadership is really important. <br />
* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].<br />
[[Category: Season of Docs]]<br />
<br />
==Writing tools don't match writing workflows==<br />
Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.<br />
===git - pros and cons of git===<br />
===wiki markups - pros and cons===<br />
===google docs - pros and cons===<br />
===gitdocs===<br />
gitdocs looks promising. Has anyone tried it and can report back?<br />
<br />
==Missing Measurement tools==<br />
<br />
==Missing templates==<br />
<br />
==Gap Analysis==<br />
<br />
==Missing quality definitions==<br />
<br />
==Glossaries and lexicon management==<br />
<br />
==Finding motivated contributors==<br />
A goal of SeasonOfDocs is to "bring open-source and technical writer communities together, to the benefit of both. Together we raise awareness of open source, of docs, and of technical writing."<br />
To realise this goal, let's consider the motivations of people involved. As explained in Eric S Raymond's first rule of open source in [http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s02.html The Cathedral and the Bazaar]:<br />
<br />
''# Every good work of [open source] software starts by scratching a developer's personal itch.''<br />
<br />
Software developers write great open-source software because they are both competent (as developers) and motivated (with an itch to scratch).<br />
<br />
The challenge we face with open source docs is that it is hard to find people who are both competent and motivated.<br />
<br />
===Software users:===<br />
Interest:<br />
* Often are very appreciative of the free software that developers have given them and want to give back in some way.<br />
* Have often been frustrated by poor documentation.<br />
* After finding a solution, are often prepared to write up a specific doc problem.<br />
* Might be prepared to write up a doc section if they feel it would be helpful and appreciated.<br />
<br />
Hindered by:<br />
* Technical ramp-up required to learn to write docs (such as git, wiki markup languages).<br />
* Lack of writing experience, experience with style guides, document structures, etc.<br />
* Lack of understanding of the documentation strategy and what sort of documentation should be written.<br />
* Often don't feel worthy to provide contributions. "Developers know the software better than I.", "I'm not a trained writer."<br />
<br />
===Software developers:===<br />
Disinterest:<br />
* Would prefer to write code.<br />
<br />
Hindered by:<br />
* Lack of writing experience, experience with style guides, document structures, etc.<br />
<br />
Interest:<br />
* Often acknowledge the importance of documentation and would like to see their product as being polished.<br />
* Might be suffering from frustrated user community asking questions because they can't find good docs.<br />
<br />
===Technical Writers===<br />
Disinterest:<br />
* Typically are not users of the open-source application, so haven't used the documentation and haven't experienced a driving itch to fix them.<br />
<br />
Interest Google Season of Docs:<br />
* Have joined Google Season of Docs, maybe wanting to learn about open source, maybe because they are getting paid, maybe because working on a sexy Google project is interesting or would look good on the resume.<br />
<br />
Interest in TheGoodDocsProject:<br />
* We have attracted multiple VOLUNTEER tech writers to help create writing templates as part of [https://thegooddocsproject.dev/ TheGoodDocsProject].<br />
* Tech writers are scratching an itch - such templates will help address challenges writers face on a daily basis.<br />
<br />
==Barriers to entry==</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_of_Docs_Lessons_Learned_2019&diff=123137Season of Docs Lessons Learned 20192020-01-25T20:33:16Z<p>Wiki-Camerons: /* Key open-source themes */</p>
<hr />
<div>[[Season_Of_Docs_2019|Season of Docs]] home page.<br />
A collation of lessons that we have learned while participating in the 2019 Season of Docs.<br />
<br />
=Organisation Application Process=<br />
==Define "Technical Writer"==<br />
When I was talking about Season Of Docs with developers and writers we often lacked a common understanding of a technical writer's role. Many focused on the simpler and most immediate problems faced. In it's broadest sense, almost anyone involved in a software project is a technical writer:<br />
* The developer who comments their code.<br />
* The user or support person answering getting started questions within a community forum.<br />
* The marketer describing the product's features.<br />
So I started using the term "Senior Technical Writer" to focus conversations on harder writing problems, such as strategy and information architecture.<br />
<br />
While everyone wants good documentation, I found that few share a clear definition of what it looks like, and fewer agree on tasks required to achieve this. The Season of Docs provided a list of [https://developers.google.com/season-of-docs/docs/project-ideas Example Projects] which helped, but I think it would useful to define technical writer roles more clearly, describing:<br />
* The value technical writers can bring to a project,<br />
* The skills they bring, <br />
* The roles they can fill,<br />
* And what writers need from developers to collectively become more effective.<br />
<br />
==Expand technical writing roles==<br />
Some common themes emerged when talking with our OSGeo projects about needs for documentation. We focused on tasks requiring high order writing skills, which are harder to find within open source communities. However, there are plenty of other important roles which are also needed. Future Season of Docs initiatives could extend the breadth of roles supported.<br />
* Triaging a documentation issue tracker was typically under-resourced. It is hard to find volunteers for non-glamourous, time-consuming roles like this. And while it isn't specifically a tech writing role, it is important for the success of a tech writing program.<br />
* We found plenty of project users who wouldn't identify as technical writers, who would like to give back to their open source community through documentation. This year's OSGeo Season of Docs tasks has focused on empowering these users to contribute to documentation.<br />
* Community building and community support is a valuable way to attract project contributions to a project, be that via documentation, code, or something else. This outreach role is a valuable role worth fostering. <br />
* Much of our documentation is written by developers using poor language choice. English documentation is often written by non-native English speakers. Future initiatives could support junior writers reviewing documentation against a specific style guide.<br />
* Many writers are not technical. They are unfamiliar with wiki formatting, git, and publishing pipelines. If we can simplify tools we will increase the pool of writers willing to contribute to our projects. (This might be a focus area for Google Summer of Code.)<br />
* Similarly, the documentation management and publishing infrastructure need to be set up and maintained. It is more within a programmer's skill-set than a technical writer's.<br />
<br />
==SeasonOfDocs blog aggregator==<br />
As many of us involved in Season Of Docs are writers, many of us will be blogging about it.<br />
* I see Sarah has: https://ffeathers.wordpress.com/2019/05/02/season-of-docs-is-now-ready-for-tech-writer-exploration/<br />
* Me too: http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html<br />
<br />
I suggest it would be handy to set up a Planet Season Of Docs blog aggregator of people involved. Something like what we have set up at the Open Source Geospatial Foundation for those of us who blog about geospatial topics. https://planet.osgeo.org/<br />
<br />
==Deadline straight after public holiday==<br />
The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.<br />
<br />
=Writer Exploration period=<br />
<br />
== Concise Summary of Project Writing Tasks ==<br />
Season Of Docs provides a list of [https://developers.google.com/season-of-docs/docs/participants/ Participating Organisations], with a summary of the project, links to the pages about tasks, and contact points. This is good, but I'd suggest slight refinements.<br />
* Descriptions of projects cover the project's technology, however, the tech writer is likely more interested in types of writing required and how it matches the writer's skill set.<br />
* I suggest keeping the list of projects concise (and probably encourage the technical description to be more concise, limited to 2 or 3 sentences).<br />
* I suggest each project summarise their requirements from a technical writer.<br />
<br />
== Volunteers welcomed ==<br />
Season of Docs only has space for a few paid writers, but this is an opportunity for projects to attract volunteer tech writers to join. Feedback from one senior tech writer I talked to:<br />
<br />
"I'm interested in Season of Docs, but I'm not in a position to commit to a fixed deliverable due to my work/life commitments, and I haven't seen anywhere I can engage as a volunteer."<br />
<br />
We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.<br />
<br />
== Communication Overload ==<br />
=== FAQ ===<br />
Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.<br />
<br />
=== Project Description Overhead ===<br />
With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects? <br />
# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.<br />
# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.<br />
<br />
=== Applicant Overload ===<br />
We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:<br />
# Ask applicants to respect the time of projects.<br />
# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)<br />
# Are you interested in volunteering, if so, then have a look at this separate list ...<br />
# ...<br />
<br />
== Doc license ==<br />
I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)<br />
<br />
= Development Phase =<br />
== Problems Open Source doc teams face ==<br />
I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.<br />
<br />
* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744<br />
* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html<br />
<br />
There are lessons in here which I think should be absorbed into Season of Docs:<br />
* Docs should start with an information architecture<br />
* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].<br />
* Community leadership is really important. <br />
* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].<br />
[[Category: Season of Docs]]<br />
<br />
==Writing tools don't match writing workflows==<br />
Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.<br />
===git - pros and cons of git===<br />
===wiki markups - pros and cons===<br />
===google docs - pros and cons===<br />
===gitdocs===<br />
gitdocs looks promising. Has anyone tried it and can report back?<br />
<br />
==Missing Measurement tools==<br />
<br />
==Missing templates==<br />
<br />
==Gap Analysis==<br />
<br />
==Missing quality definitions==<br />
<br />
==Glossaries and lexicon management==<br />
<br />
==Finding motivated contributors==<br />
<br />
==Barriers to entry==</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_of_Docs_Lessons_Learned_2019&diff=123017Season of Docs Lessons Learned 20192020-01-14T19:30:25Z<p>Wiki-Camerons: /* =google docs - pros and cons */</p>
<hr />
<div>[[Season_Of_Docs_2019|Season of Docs]] home page.<br />
A collation of lessons that we have learned while participating in the 2019 Season of Docs.<br />
<br />
=Organisation Application Process=<br />
==Define "Technical Writer"==<br />
When I was talking about Season Of Docs with developers and writers we often lacked a common understanding of a technical writer's role. Many focused on the simpler and most immediate problems faced. In it's broadest sense, almost anyone involved in a software project is a technical writer:<br />
* The developer who comments their code.<br />
* The user or support person answering getting started questions within a community forum.<br />
* The marketer describing the product's features.<br />
So I started using the term "Senior Technical Writer" to focus conversations on harder writing problems, such as strategy and information architecture.<br />
<br />
While everyone wants good documentation, I found that few share a clear definition of what it looks like, and fewer agree on tasks required to achieve this. The Season of Docs provided a list of [https://developers.google.com/season-of-docs/docs/project-ideas Example Projects] which helped, but I think it would useful to define technical writer roles more clearly, describing:<br />
* The value technical writers can bring to a project,<br />
* The skills they bring, <br />
* The roles they can fill,<br />
* And what writers need from developers to collectively become more effective.<br />
<br />
==Expand technical writing roles==<br />
Some common themes emerged when talking with our OSGeo projects about needs for documentation. We focused on tasks requiring high order writing skills, which are harder to find within open source communities. However, there are plenty of other important roles which are also needed. Future Season of Docs initiatives could extend the breadth of roles supported.<br />
* Triaging a documentation issue tracker was typically under-resourced. It is hard to find volunteers for non-glamourous, time-consuming roles like this. And while it isn't specifically a tech writing role, it is important for the success of a tech writing program.<br />
* We found plenty of project users who wouldn't identify as technical writers, who would like to give back to their open source community through documentation. This year's OSGeo Season of Docs tasks has focused on empowering these users to contribute to documentation.<br />
* Community building and community support is a valuable way to attract project contributions to a project, be that via documentation, code, or something else. This outreach role is a valuable role worth fostering. <br />
* Much of our documentation is written by developers using poor language choice. English documentation is often written by non-native English speakers. Future initiatives could support junior writers reviewing documentation against a specific style guide.<br />
* Many writers are not technical. They are unfamiliar with wiki formatting, git, and publishing pipelines. If we can simplify tools we will increase the pool of writers willing to contribute to our projects. (This might be a focus area for Google Summer of Code.)<br />
* Similarly, the documentation management and publishing infrastructure need to be set up and maintained. It is more within a programmer's skill-set than a technical writer's.<br />
<br />
==SeasonOfDocs blog aggregator==<br />
As many of us involved in Season Of Docs are writers, many of us will be blogging about it.<br />
* I see Sarah has: https://ffeathers.wordpress.com/2019/05/02/season-of-docs-is-now-ready-for-tech-writer-exploration/<br />
* Me too: http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html<br />
<br />
I suggest it would be handy to set up a Planet Season Of Docs blog aggregator of people involved. Something like what we have set up at the Open Source Geospatial Foundation for those of us who blog about geospatial topics. https://planet.osgeo.org/<br />
<br />
==Deadline straight after public holiday==<br />
The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.<br />
<br />
=Writer Exploration period=<br />
<br />
== Concise Summary of Project Writing Tasks ==<br />
Season Of Docs provides a list of [https://developers.google.com/season-of-docs/docs/participants/ Participating Organisations], with a summary of the project, links to the pages about tasks, and contact points. This is good, but I'd suggest slight refinements.<br />
* Descriptions of projects cover the project's technology, however, the tech writer is likely more interested in types of writing required and how it matches the writer's skill set.<br />
* I suggest keeping the list of projects concise (and probably encourage the technical description to be more concise, limited to 2 or 3 sentences).<br />
* I suggest each project summarise their requirements from a technical writer.<br />
<br />
== Volunteers welcomed ==<br />
Season of Docs only has space for a few paid writers, but this is an opportunity for projects to attract volunteer tech writers to join. Feedback from one senior tech writer I talked to:<br />
<br />
"I'm interested in Season of Docs, but I'm not in a position to commit to a fixed deliverable due to my work/life commitments, and I haven't seen anywhere I can engage as a volunteer."<br />
<br />
We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.<br />
<br />
== Communication Overload ==<br />
=== FAQ ===<br />
Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.<br />
<br />
=== Project Description Overhead ===<br />
With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects? <br />
# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.<br />
# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.<br />
<br />
=== Applicant Overload ===<br />
We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:<br />
# Ask applicants to respect the time of projects.<br />
# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)<br />
# Are you interested in volunteering, if so, then have a look at this separate list ...<br />
# ...<br />
<br />
== Doc license ==<br />
I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)<br />
<br />
= Development Phase =<br />
== Problems Open Source doc teams face ==<br />
I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.<br />
<br />
* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744<br />
* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html<br />
<br />
There are lessons in here which I think should be absorbed into Season of Docs:<br />
* Docs should start with an information architecture<br />
* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].<br />
* Community leadership is really important. <br />
* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].<br />
[[Category: Season of Docs]]<br />
<br />
==Writing tools don't match writing workflows==<br />
Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.<br />
===git - pros and cons of git===<br />
===wiki markups - pros and cons===<br />
===google docs - pros and cons===<br />
===gitdocs===<br />
gitdocs looks promising. Has anyone tried it and can report back?<br />
<br />
==Missing Measurement tools==<br />
<br />
==Missing templates==<br />
<br />
==Gap Analysis==<br />
<br />
==Missing quality definitions==<br />
<br />
==Glossaries and lexicon management==<br />
<br />
==Finding motivated contributors==<br />
<br />
==Barriers to entry==<br />
<br />
=Key open-source themes=<br />
* It is all about collaboration<br />
* The health of the community behind the project is more important than the technology. A healthy community will solve technical problems. <br />
* Sustainability<br />
* Modularity<br />
* Inflection points<br />
** from individual to a group<br />
** from startup, focusing on features, to quality focusing on process<br />
* Grit<br />
* Maintaining momentum<br />
* Work within a gift economy<br />
* Meritocracy<br />
* Do-ocracy<br />
* Respect and support<br />
* Diversity<br />
* Time-shifting work and communication (email lists are great)<br />
* Bouncing ideas off people<br />
* Transparency<br />
* Increasing signal-to-noise ratio<br />
* Motivation<br />
** Vision<br />
* Innovation<br />
** Innovation labs is a myth<br />
** There are more people in the rest of the world trying to solve your problem than you can ever find in your team.<br />
* Measurement<br />
** Measurement and assessment is time-consuming<br />
** We use trust metrics<br />
** It helps to create trust metrics</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_of_Docs_Lessons_Learned_2019&diff=123016Season of Docs Lessons Learned 20192020-01-14T19:29:59Z<p>Wiki-Camerons: /* Development Phase */</p>
<hr />
<div>[[Season_Of_Docs_2019|Season of Docs]] home page.<br />
A collation of lessons that we have learned while participating in the 2019 Season of Docs.<br />
<br />
=Organisation Application Process=<br />
==Define "Technical Writer"==<br />
When I was talking about Season Of Docs with developers and writers we often lacked a common understanding of a technical writer's role. Many focused on the simpler and most immediate problems faced. In it's broadest sense, almost anyone involved in a software project is a technical writer:<br />
* The developer who comments their code.<br />
* The user or support person answering getting started questions within a community forum.<br />
* The marketer describing the product's features.<br />
So I started using the term "Senior Technical Writer" to focus conversations on harder writing problems, such as strategy and information architecture.<br />
<br />
While everyone wants good documentation, I found that few share a clear definition of what it looks like, and fewer agree on tasks required to achieve this. The Season of Docs provided a list of [https://developers.google.com/season-of-docs/docs/project-ideas Example Projects] which helped, but I think it would useful to define technical writer roles more clearly, describing:<br />
* The value technical writers can bring to a project,<br />
* The skills they bring, <br />
* The roles they can fill,<br />
* And what writers need from developers to collectively become more effective.<br />
<br />
==Expand technical writing roles==<br />
Some common themes emerged when talking with our OSGeo projects about needs for documentation. We focused on tasks requiring high order writing skills, which are harder to find within open source communities. However, there are plenty of other important roles which are also needed. Future Season of Docs initiatives could extend the breadth of roles supported.<br />
* Triaging a documentation issue tracker was typically under-resourced. It is hard to find volunteers for non-glamourous, time-consuming roles like this. And while it isn't specifically a tech writing role, it is important for the success of a tech writing program.<br />
* We found plenty of project users who wouldn't identify as technical writers, who would like to give back to their open source community through documentation. This year's OSGeo Season of Docs tasks has focused on empowering these users to contribute to documentation.<br />
* Community building and community support is a valuable way to attract project contributions to a project, be that via documentation, code, or something else. This outreach role is a valuable role worth fostering. <br />
* Much of our documentation is written by developers using poor language choice. English documentation is often written by non-native English speakers. Future initiatives could support junior writers reviewing documentation against a specific style guide.<br />
* Many writers are not technical. They are unfamiliar with wiki formatting, git, and publishing pipelines. If we can simplify tools we will increase the pool of writers willing to contribute to our projects. (This might be a focus area for Google Summer of Code.)<br />
* Similarly, the documentation management and publishing infrastructure need to be set up and maintained. It is more within a programmer's skill-set than a technical writer's.<br />
<br />
==SeasonOfDocs blog aggregator==<br />
As many of us involved in Season Of Docs are writers, many of us will be blogging about it.<br />
* I see Sarah has: https://ffeathers.wordpress.com/2019/05/02/season-of-docs-is-now-ready-for-tech-writer-exploration/<br />
* Me too: http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html<br />
<br />
I suggest it would be handy to set up a Planet Season Of Docs blog aggregator of people involved. Something like what we have set up at the Open Source Geospatial Foundation for those of us who blog about geospatial topics. https://planet.osgeo.org/<br />
<br />
==Deadline straight after public holiday==<br />
The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.<br />
<br />
=Writer Exploration period=<br />
<br />
== Concise Summary of Project Writing Tasks ==<br />
Season Of Docs provides a list of [https://developers.google.com/season-of-docs/docs/participants/ Participating Organisations], with a summary of the project, links to the pages about tasks, and contact points. This is good, but I'd suggest slight refinements.<br />
* Descriptions of projects cover the project's technology, however, the tech writer is likely more interested in types of writing required and how it matches the writer's skill set.<br />
* I suggest keeping the list of projects concise (and probably encourage the technical description to be more concise, limited to 2 or 3 sentences).<br />
* I suggest each project summarise their requirements from a technical writer.<br />
<br />
== Volunteers welcomed ==<br />
Season of Docs only has space for a few paid writers, but this is an opportunity for projects to attract volunteer tech writers to join. Feedback from one senior tech writer I talked to:<br />
<br />
"I'm interested in Season of Docs, but I'm not in a position to commit to a fixed deliverable due to my work/life commitments, and I haven't seen anywhere I can engage as a volunteer."<br />
<br />
We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.<br />
<br />
== Communication Overload ==<br />
=== FAQ ===<br />
Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.<br />
<br />
=== Project Description Overhead ===<br />
With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects? <br />
# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.<br />
# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.<br />
<br />
=== Applicant Overload ===<br />
We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:<br />
# Ask applicants to respect the time of projects.<br />
# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)<br />
# Are you interested in volunteering, if so, then have a look at this separate list ...<br />
# ...<br />
<br />
== Doc license ==<br />
I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)<br />
<br />
= Development Phase =<br />
== Problems Open Source doc teams face ==<br />
I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.<br />
<br />
* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744<br />
* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html<br />
<br />
There are lessons in here which I think should be absorbed into Season of Docs:<br />
* Docs should start with an information architecture<br />
* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].<br />
* Community leadership is really important. <br />
* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].<br />
[[Category: Season of Docs]]<br />
<br />
==Writing tools don't match writing workflows==<br />
Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.<br />
===git - pros and cons of git===<br />
===wiki markups - pros and cons===<br />
===google docs - pros and cons==<br />
===gitdocs===<br />
gitdocs looks promising. Has anyone tried it and can report back?<br />
<br />
==Missing Measurement tools==<br />
<br />
==Missing templates==<br />
<br />
==Gap Analysis==<br />
<br />
==Missing quality definitions==<br />
<br />
==Glossaries and lexicon management==<br />
<br />
==Finding motivated contributors==<br />
<br />
==Barriers to entry==<br />
<br />
=Key open-source themes=<br />
* It is all about collaboration<br />
* The health of the community behind the project is more important than the technology. A healthy community will solve technical problems. <br />
* Sustainability<br />
* Modularity<br />
* Inflection points<br />
** from individual to a group<br />
** from startup, focusing on features, to quality focusing on process<br />
* Grit<br />
* Maintaining momentum<br />
* Work within a gift economy<br />
* Meritocracy<br />
* Do-ocracy<br />
* Respect and support<br />
* Diversity<br />
* Time-shifting work and communication (email lists are great)<br />
* Bouncing ideas off people<br />
* Transparency<br />
* Increasing signal-to-noise ratio<br />
* Motivation<br />
** Vision<br />
* Innovation<br />
** Innovation labs is a myth<br />
** There are more people in the rest of the world trying to solve your problem than you can ever find in your team.<br />
* Measurement<br />
** Measurement and assessment is time-consuming<br />
** We use trust metrics<br />
** It helps to create trust metrics</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Season_of_Docs_Lessons_Learned_2019&diff=122622Season of Docs Lessons Learned 20192019-12-08T06:31:11Z<p>Wiki-Camerons: /* Development Phase */</p>
<hr />
<div>[[Season_Of_Docs_2019|Season of Docs]] home page.<br />
A collation of lessons that we have learned while participating in the 2019 Season of Docs.<br />
<br />
=Organisation Application Process=<br />
==Define "Technical Writer"==<br />
When I was talking about Season Of Docs with developers and writers we often lacked a common understanding of a technical writer's role. Many focused on the simpler and most immediate problems faced. In it's broadest sense, almost anyone involved in a software project is a technical writer:<br />
* The developer who comments their code.<br />
* The user or support person answering getting started questions within a community forum.<br />
* The marketer describing the product's features.<br />
So I started using the term "Senior Technical Writer" to focus conversations on harder writing problems, such as strategy and information architecture.<br />
<br />
While everyone wants good documentation, I found that few share a clear definition of what it looks like, and fewer agree on tasks required to achieve this. The Season of Docs provided a list of [https://developers.google.com/season-of-docs/docs/project-ideas Example Projects] which helped, but I think it would useful to define technical writer roles more clearly, describing:<br />
* The value technical writers can bring to a project,<br />
* The skills they bring, <br />
* The roles they can fill,<br />
* And what writers need from developers to collectively become more effective.<br />
<br />
==Expand technical writing roles==<br />
Some common themes emerged when talking with our OSGeo projects about needs for documentation. We focused on tasks requiring high order writing skills, which are harder to find within open source communities. However, there are plenty of other important roles which are also needed. Future Season of Docs initiatives could extend the breadth of roles supported.<br />
* Triaging a documentation issue tracker was typically under-resourced. It is hard to find volunteers for non-glamourous, time-consuming roles like this. And while it isn't specifically a tech writing role, it is important for the success of a tech writing program.<br />
* We found plenty of project users who wouldn't identify as technical writers, who would like to give back to their open source community through documentation. This year's OSGeo Season of Docs tasks has focused on empowering these users to contribute to documentation.<br />
* Community building and community support is a valuable way to attract project contributions to a project, be that via documentation, code, or something else. This outreach role is a valuable role worth fostering. <br />
* Much of our documentation is written by developers using poor language choice. English documentation is often written by non-native English speakers. Future initiatives could support junior writers reviewing documentation against a specific style guide.<br />
* Many writers are not technical. They are unfamiliar with wiki formatting, git, and publishing pipelines. If we can simplify tools we will increase the pool of writers willing to contribute to our projects. (This might be a focus area for Google Summer of Code.)<br />
* Similarly, the documentation management and publishing infrastructure need to be set up and maintained. It is more within a programmer's skill-set than a technical writer's.<br />
<br />
==SeasonOfDocs blog aggregator==<br />
As many of us involved in Season Of Docs are writers, many of us will be blogging about it.<br />
* I see Sarah has: https://ffeathers.wordpress.com/2019/05/02/season-of-docs-is-now-ready-for-tech-writer-exploration/<br />
* Me too: http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html<br />
<br />
I suggest it would be handy to set up a Planet Season Of Docs blog aggregator of people involved. Something like what we have set up at the Open Source Geospatial Foundation for those of us who blog about geospatial topics. https://planet.osgeo.org/<br />
<br />
==Deadline straight after public holiday==<br />
The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.<br />
<br />
=Writer Exploration period=<br />
<br />
== Concise Summary of Project Writing Tasks ==<br />
Season Of Docs provides a list of [https://developers.google.com/season-of-docs/docs/participants/ Participating Organisations], with a summary of the project, links to the pages about tasks, and contact points. This is good, but I'd suggest slight refinements.<br />
* Descriptions of projects cover the project's technology, however, the tech writer is likely more interested in types of writing required and how it matches the writer's skill set.<br />
* I suggest keeping the list of projects concise (and probably encourage the technical description to be more concise, limited to 2 or 3 sentences).<br />
* I suggest each project summarise their requirements from a technical writer.<br />
<br />
== Volunteers welcomed ==<br />
Season of Docs only has space for a few paid writers, but this is an opportunity for projects to attract volunteer tech writers to join. Feedback from one senior tech writer I talked to:<br />
<br />
"I'm interested in Season of Docs, but I'm not in a position to commit to a fixed deliverable due to my work/life commitments, and I haven't seen anywhere I can engage as a volunteer."<br />
<br />
We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.<br />
<br />
== Communication Overload ==<br />
=== FAQ ===<br />
Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.<br />
<br />
=== Project Description Overhead ===<br />
With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects? <br />
# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.<br />
# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.<br />
<br />
=== Applicant Overload ===<br />
We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:<br />
# Ask applicants to respect the time of projects.<br />
# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)<br />
# Are you interested in volunteering, if so, then have a look at this separate list ...<br />
# ...<br />
<br />
== Doc license ==<br />
I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)<br />
<br />
= Development Phase =<br />
== Problems Open Source doc teams face ==<br />
I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.<br />
<br />
* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744<br />
* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html<br />
<br />
There are lessons in here which I think should be absorbed into Season of Docs:<br />
* Docs should start with an information architecture<br />
* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].<br />
* Community leadership is really important. <br />
* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].<br />
[[Category: Season of Docs]]<br />
<br />
==Writing tools are painful==<br />
Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=122419Lexicon Committee2019-11-23T00:16:47Z<p>Wiki-Camerons: /* Committee members */</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeo.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on Open Source (which mitigates project risk). We should link to the source code project in github.<br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list].<br />
<br />
== Committee members ==<br />
* [[User:camerons| Cameron Shorter]] (OSGeoLive, WriteTheDocs)<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* [[User:Jgrocha|Jorge Gustavo Rocha]] (OSGeo/QGIS)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire at any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=122284Lexicon Committee2019-11-16T06:09:57Z<p>Wiki-Camerons: </p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the Open Source Geospatial (OSGeo) context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays the following roles:<br />
<br />
# Act as the gatekeeper of terms to ensure quality checks of contributions.<br />
# Provide a central terminology knowledge for alignment of terms and concepts. <br />
# Facilitate the flow of terminology knowledge to terminology authors and users. <br />
# Support the use of best practices in writing terms.<br />
# Facilitate developing consistent terminology between OSGeo projects.<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has setup https://osgeo.geolexica.org/ to serve OSGeo in managing the lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages it provides a “propose new term” and “propose changes to this term" buttons. This allows users to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on Open Source (which mitigates project risk). We should link to the source code project in github.<br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list].<br />
<br />
== Committee members ==<br />
TBD: Once formed, the following people have volunteered to join this committee:<br />
<br />
* Cameron Shorter<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=122276Lexicon Committee2019-11-15T20:56:35Z<p>Wiki-Camerons: /* Communication */</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the OSGeo context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays two essential roles:<br />
<br />
# As the gatekeeper of terms to ensure quality checks of contributions<br />
# As the seat of central terminology knowledge for alignment of terms and concepts. To facilitate the flow of terminology knowledge to terminology authors and users. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
TBD: Cameron's version of the role of the committee:<br />
# Support the use of best practices in writing terms<br />
# Facilitate developing consistent terminology between OSGeo projects<br />
# Provide an authoritative repository of OSGeo terminology<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has volunteered to setup https://osgeo.geolexica.org/ to serve OSGeo in managing its lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages we can offer a “propose new term” and “propose changes to this term" buttons. This allows user to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on Open Source (which mitigates project risk). We should link to the source code project in github.<br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
We communicate on the [https://lists.osgeo.org/mailman/listinfo/lexicon OSGeo Lexicon email list].<br />
<br />
== Committee members ==<br />
TBD: Once formed, the following people have volunteered to join this committee:<br />
<br />
* Cameron Shorter<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=122229Lexicon Committee2019-11-04T20:30:16Z<p>Wiki-Camerons: note that this committee is an OSGeo Special Interest Group</p>
<hr />
<div>The Lexicon committee is an [https://wiki.osgeo.org/wiki/Interest_Groups OSGeo Special Interest Group], responsible for coordinating official definitions for terminology used within the OSGeo context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays two essential roles:<br />
<br />
# As the gatekeeper of terms to ensure quality checks of contributions<br />
# As the seat of central terminology knowledge for alignment of terms and concepts. To facilitate the flow of terminology knowledge to terminology authors and users. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
TBD: Cameron's version of the role of the committee:<br />
# Support the use of best practices in writing terms<br />
# Facilitate developing consistent terminology between OSGeo projects<br />
# Provide an authoritative repository of OSGeo terminology<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has volunteered to setup https://osgeo.geolexica.org/ to serve OSGeo in managing its lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages we can offer a “propose new term” and “propose changes to this term" buttons. This allows user to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on Open Source (which mitigates project risk). We should link to the source code project in github.<br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
Communication has started on the [https://lists.osgeo.org/mailman/listinfo/standards OSGeo Standards] email list. Once officially formed, we plan to move to a new email list.<br />
<br />
== Committee members ==<br />
TBD: Once formed, the following people have volunteered to join this committee:<br />
<br />
* Cameron Shorter<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Interest_Groups&diff=122228Interest Groups2019-11-04T20:16:51Z<p>Wiki-Camerons: /* Proposed Interest Groups */ Lexicon Committee</p>
<hr />
<div>''This page documents the current dicsussion and has not yet been approved as official OSGeo policy!''<br />
<br />
Interest Groups are less formal than [[Local Chapters]] and function as coordination and discussion area for like minded people who want to work on common projects with a local focus. <br />
<br />
=== How to start an Interest Group ===<br />
Interest Groups should first start their own Wiki page, link it from this page and add a member list. After some time when there is a substantial list of interested people they can officially request for a mailing list under the OSGeo domain. (Until then WebCom/board must have worked out how to name them to keep things manageable).<br />
<br />
=== Guidelines ===<br />
* Typically an interest group would focus on a region, content or infrastructure. <br />
* An interest group should not overlap or replicate other existing OSGeo projects if at all possible. Therefore, a thorough search/review of existing projects is necessary and open invitations made through the OSGeo discussion list.<br />
* The OSGeo does not want to highjack, take over or interfere with any groups that already function well. The focus is on cooperation and collaboration.<br />
<br />
== Proposed Interest Groups ==<br />
* (add your proposal here)<br />
* [[Catala]] <br />
* [[Archaeology]]<br />
* [[Women Chapter]]<br />
* [[Lexicon Committee]]<br />
=== See also === <br />
* [[Local Chapters]]<br />
* [[Like Minded Regional Organizations]]</div>Wiki-Cameronshttps://wiki.osgeo.org/w/index.php?title=Lexicon_Committee&diff=122203Lexicon Committee2019-10-26T19:35:55Z<p>Wiki-Camerons: </p>
<hr />
<div>The Lexicon committee is responsible for coordinating official definitions for terminology used within the OSGeo context. The committee is drawn from the OSGeo, OGC and ISO communities and is based on merit and interest.<br />
<br />
= Purpose = <br />
<br />
The Lexicon committee plays two essential roles:<br />
<br />
# As the gatekeeper of terms to ensure quality checks of contributions<br />
# As the seat of central terminology knowledge for alignment of terms and concepts. To facilitate the flow of terminology knowledge to terminology authors and users. <br />
<br />
The committee involves individual representation from external groups including ISO/TC 211 and OGC in order to leverage their experience in terminology, which is useful in situations such as alerting on cross-organization alignment of concepts or term duplication.<br />
<br />
TBD: Cameron's version of the role of the committee:<br />
# Support the use of best practices in writing terms<br />
# Facilitate developing consistent terminology between OSGeo projects<br />
# Provide an authoritative repository of OSGeo terminology<br />
# Act as a conduit of terms between OSGeo projects, OSGeo, OGC and ISO. <br />
<br />
= Online presence =<br />
<br />
Terminology isn’t useful until people use them, which means people need to first know they exist and what they mean. The Geolexica initiative has volunteered to setup https://osgeo.geolexica.org/ to serve OSGeo in managing its lexicon database. <br />
<br />
Geolexica serves human-readable concepts and terms, as well as machine-readable JSON, allowing APIs to directly consume the content. It currently serves ISO/TC 211’s terminology management group in making its multi-lingual geographic information terminology available on the internet (https://www.geolexica.org).<br />
<br />
To minimize friction in the feedback process, for every term offered in the OSGeo terminology pages we can offer a “propose new term” and “propose changes to this term" buttons. This allows user to directly go to the issue platform (e.g. GitHub) to make the suggested changes.<br />
<br />
The structure of Geolexica is designed for efficiency with streamlined management and operations. Terms are stored in structured data (YAML) files, and are directly deployable to the website. The website operates according to best practices, and is served as a static website with dynamic search functionality. Security and performance have always been key considerations.<br />
<br />
TBD: We should mention that the Geolexia management software is based on Open Source (which mitigates project risk). We should link to the source code project in github.<br />
<br />
OSGeo terms will additionally be published at:<br />
* OSGeoLive<br />
* TBD OSGeo Journal?<br />
<br />
= Coordination =<br />
<br />
== Initial load and data cleanup ==<br />
<br />
The initial load of the terms will involve a bulk load from cleaned terms and definitions sourced from prior OSGeo glossaries. Geolexica could easily handle the initial conversion from table format into the desired structured data format.<br />
<br />
As of 2019-10, the cleanup process has already [https://docs.google.com/spreadsheets/d/19tulyAEDN5Q5n-u_jlmXIKQjPI2Lwv6fh5Orad1mz1I/edit#gid=0 started].<br />
<br />
== Updates ==<br />
* New terms, or improvements to existing terms may be proposed at any time, by anyone in the community.<br />
* It is recommended that proposed term updates are initially discussed and refined on the Lexicon email list. TBD: Link to list once setup.<br />
* Terms can then be submitted to the GeoLexia website. TBD explain how.<br />
* The lexicon committee will periodically review and approve new terms.<br />
* The lexicon committee will review and update terms at least annually, in line with the OSGeoLive documentation build cycle.<br />
<br />
== Communication ==<br />
Communication has started on the [https://lists.osgeo.org/mailman/listinfo/standards OSGeo Standards] email list. Once officially formed, we plan to move to a new email list.<br />
<br />
== Committee members ==<br />
TBD: Once formed, the following people have volunteered to join this committee:<br />
<br />
* Cameron Shorter<br />
* Rob Atkinson (OGC)<br />
* Ronald Tse (ISO/TC 211, ISO Geodetic Registry Registration Authority, Ribose Inc.)<br />
* Reese Plews (ISO/TC 211, Terminology Management Group)<br />
* ... others welcomed<br />
<br />
Past members. We thank these prior members for their contributions:<br />
* None yet<br />
<br />
Selection of new members is determined by committee member vote. Committee members may retire any time. If a committee member becomes inactive for many months they may be invited to retire, and if unresponsive they may be retired by the existing committee.<br />
<br />
==Decisions==<br />
Decisions are based on voting using the following:<br />
* +1: For<br />
* +0: Mildly for, but mostly indifferent<br />
* 0: Indifferent<br />
* -0: Mildly against, but mostly indifferent<br />
* -1: Strongly against. This is expected to be accompanied by a reason.<br />
<br />
For most decisions, a motion is raised within one of the committee open forums (IRC, email list, etc) and those present vote and decide. Should a decision:<br />
* Be strategic or impact many within the committee,<br />
* Or if there be contention in deciding, and after discussion at least one member is still strongly against the motion, by continuing to vote -1,<br />
* Then the motion should be referred to the committee.<br />
<br />
For motions presented to the committee, a motion is considered passed when there are more committee +1 votes than -1 votes, and either all committee members have voted, or 1 week has passed. In the case of a tie, the committee chair shall have 1.5 votes.<br />
<br />
==Expectations of committee members==<br />
* Contribute to or related activities when the committee is active.<br />
* Help with whatever dirty work is required to keep the project moving forward.<br />
* Monitor committee conversations on our email list.<br />
<br />
[[Category: Lexicon]]</div>Wiki-Camerons