Difference between revisions of "Season of Docs Ideas 2019"
Jump to navigation
Jump to search
(add headings to formatting) |
|||
| Line 5: | Line 5: | ||
=Leveraging Google’s Season-of-Docs= | =Leveraging Google’s Season-of-Docs= | ||
| − | + | Google’s [https://developers.google.com/season-of-docs/ Season-of-Docs] is an initiative to bring open source and technical writer communities together to write documentation. We propose we use this initiative as a focal point to attract a collaborative community to pilot big ideas. In particular: | |
| − | * | + | * Open source projects face sustainability challenges. How will docs developed during Season-Of-Docs be maintained long term? |
| − | * | + | * Can a writer’s expertise be amplified to help community users and developers write good docs more effectively and efficiently? |
| + | * Could best practices developed in one project be applied to the greater open source eco-system? | ||
| − | We propose to focus on one (or more) writing initiatives, for one of our leading OSGeo projects. Goals should focus on:* | + | We propose to focus on one (or more) writing initiatives, for one of our leading OSGeo projects. Goals should focus on: |
| − | * | + | * Being directly applicable for the project. |
| − | * | + | * Be captured as a template, which can be easily applied to other OSGeo projects. Ideally this will grow into an initiative which is of value to all open source projects. |
| + | * Engages a Season-of-Docs sponsored writer, along with volunteers from project and writing communities. | ||
| − | == | + | ==Key roles sought== |
| − | * | + | * '''Mentor''': As an experienced project team member, provide technical mentorship toward a writing initiative. |
| − | * | + | * '''Writer''': As someone keen to give back to open source through docs, volunteer to be mentored and tackle our OSGeo writing initiatives. |
| − | * | + | * '''Senior writer''': Drive the writing aspects of an initiative, including empowering other participants. (Eligible for a stipend from Google). |
| − | * | + | * '''Learning expert''': Help shape documentation templates and guides by linking back to educational theory. (This role is highly prized). |
| − | * | + | * '''Administrator''': As an engaged OSGeo community member, act as a Season-of-Docs administrator. |
| − | == | + | ==Interested?== |
If you are considering helping, or maybe just want to learn a bit more, then please reach out to us on our [https://lists.osgeo.org/mailman/listinfo/seasonofdocs email list]. If keen, then add yourself to the list below. ''(Be concise: Name, brief background, how you’d like to contribute.)'' | If you are considering helping, or maybe just want to learn a bit more, then please reach out to us on our [https://lists.osgeo.org/mailman/listinfo/seasonofdocs email list]. If keen, then add yourself to the list below. ''(Be concise: Name, brief background, how you’d like to contribute.)'' | ||
| − | == | + | ==People keen to take part== |
| − | * | + | * '''Cameron Shorter''': Geospatial business analyst. Co-founder of OSGeoLive. Co-editor of OSGeoLive doc templates; reviewer of most of the 50 Project Overview and Quickstart documents. Ex-board member of OSGeo Foundation. Keen to provide connections to our community and to be practically involved in writing initiatives. |
| − | * | + | * '''Astrid Emde''': Senior GIS consultant at WhereGroup in Bonn, Germany. OSGeo board member and secretary. Awarded the Sol Katz award for leadership and longtime contributions to open source geospatial communities. Contributor to OSGeoLive, the OSGeo marketing committee and co-coordinator of meetups, code-sprints, and the annual German-speaking open source geospatial conference. She likes documentation and teaching people OSGeo Software. Keen to provide connections to our community and to be practically involved in writing initiatives. |
| − | * | + | * '''Johanna Boltman''': Ex-English teacher, IT admin, and user of open source software as a geospatial officer at a local council. Keen to be mentored in writing docs. |
| − | * | + | * '''Belinda Baker''': Background in writing process documentation and user of open source software as a GIS Consultant at a software company. Keen to be mentored in writing docs. |
| − | * | + | * '''Liam Turner''': GIS Specialist for NSW Government (Australia), previously a high school physics teacher. User of open source technical documentation, keen to make a contribution. |
| − | * | + | * '''Nicolas Roelandt:''' Geospatial engineer at the French Institute of Science and Technology for Transport, Development and Networks. OSGeo charter member and OSGeoLive Project Steering Committee (PSC) member. Works on OSGeoLive documentation and translation build process (using the Transifex platform). Keen to support others in the use of these tools. |
| − | * | + | * '''Luca Delucchi:''' Geographer; OSGeo and Open Street Map contributor and advocate. Core developer and translator of the GRASS GIS project; main developer of pyModis library; OSGeoLive and ZOO-Project contributor; president of the Italian OSGeo local chapter. Willing to help improve Jupyter interactive notebook documents in line with a developed template and writing instructions, if one is developed and committed to. |
| − | * | + | * '''Nick Bearman: '''Teaching Fellow in Geospatial Analysis (University College London) and GIS Trainer & Consultant (Geospatial Training Solutions). Contributed to QGIS documentation. Write and deliver GIS training courses to a variety of participants. Keen to learn how to contribute more effectively, particularly to QGIS documentation. Also looking to run a workshop on how to contribute to open source documentation at upcoming FOSS4G UK event in Edinburgh, UK in September 2019. |
| − | * | + | * '''Sergio Acosta y Lara:''' Architect (Universidad de la República/UdelaR) working with Geographic Information Technologies for nearly 30 years. In charge of the Department of Geomatics (Ministry of Transport and Public Works) and member of several Working Groups for Technical Specifications of the IDEuy (Spatial Data Infrastructure of Uruguay). Charter Member of the OSGeo Foundation (Open Geospatial Foundation) and member of the Advisory Board of the Geo4all initiative, Regional chair for Iberoamerica and co-editor of its newsletter. Coordinator for gvSIG Batoví (design and development of a GIS applied to educational environments for the Plan Ceibal (OLPC initiative for Uruguay) based on gvSIG. Co-coordinator of the gvSIG Uruguay Community (web) and of its blog. |
| − | * | + | * <add your name here> |
| Line 43: | Line 45: | ||
=Ideas= | =Ideas= | ||
| − | == | + | ==Best practice templates== |
Good documentation benefits from access to cross-disciplinary skills. Expertise is typically spread across developers, users, domain experts, teachers, technical writers, graphic artists, and translators. Ramp-up time is high for any group attempting to learn another’s skill-set. This creates a significant barrier to entry. | Good documentation benefits from access to cross-disciplinary skills. Expertise is typically spread across developers, users, domain experts, teachers, technical writers, graphic artists, and translators. Ramp-up time is high for any group attempting to learn another’s skill-set. This creates a significant barrier to entry. | ||
| Line 52: | Line 54: | ||
| − | Potential resources:* | + | Potential resources: |
| − | * | + | * Daniele Procida’s [https://www.divio.com/blog/documentation/ What nobody tells you about documentation]. |
| − | * | + | * [https://github.com/mdyd-dev/nearme-documentation/tree/master/marketplace_builder/views/pages/doc-templates Nearme writing templates] with [https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts accompanying blog post]. |
| − | * | + | * [http://cameronshorter.blogspot.com/2018/06/technical-documentation-writing.html Document type definitions]. |
| − | * | + | * [https://wiki.osgeo.org/wiki/OSGeoLive_AddProject#Documentation Writing instructions for OSGeoLive Project Overviews and Quickstarts]. |
| − | * | + | * The [https://www.writethedocs.org/about/stay-connected/ Write-The-Docs community] are a likely source of potential co-contributors and defacto owners of such templates. |
| − | * | + | * [https://www.cebm.net/wp-content/uploads/2016/09/Blooms-Taxonomy-Teacher-Planning-Kit.pdf Bloom’s Taxonomy: Teacher Planning Kit] is helpful for selecting language for training. |
| + | * Someone has suggested ISO standards, but you need to pay to use them, and they appear overly verbose: [https://en.wikipedia.org/wiki/ISO/IEC_JTC_1/SC_7#Published_standards ISO/IEC/IEEE 26511, 25612, 25613, 25614, 25615]. | ||
| − | + | ==Other doc types for OSGeoLive== | |
| − | |||
| − | == | ||
To date, our OSGeoLive community have been sustainably maintaining two of the easier documentation types: Project Overviews and Quickstarts. Established OSGeo projects also have documentation, in various stages of currency, completion, relevance, verbosity, and quality. | To date, our OSGeoLive community have been sustainably maintaining two of the easier documentation types: Project Overviews and Quickstarts. Established OSGeo projects also have documentation, in various stages of currency, completion, relevance, verbosity, and quality. | ||
| Line 68: | Line 69: | ||
I believe we are ready to extend our consistency and best practices to some of the harder documentation types - such as tutorials, workshops and howtos. We should start by focusing on one of OSGeo’s flagship projects, such as QGIS or PostGIS. Join the project’s existing documentation initiatives. Provide feedback and improvements as required. Build templates and writing instructions which can be adopted by other projects. Integrate these with the OSGeoLive publishing and translation pipeline. | I believe we are ready to extend our consistency and best practices to some of the harder documentation types - such as tutorials, workshops and howtos. We should start by focusing on one of OSGeo’s flagship projects, such as QGIS or PostGIS. Join the project’s existing documentation initiatives. Provide feedback and improvements as required. Build templates and writing instructions which can be adopted by other projects. Integrate these with the OSGeoLive publishing and translation pipeline. | ||
| − | Resources:* | + | Resources: |
| − | + | * To help position training with other courses, it helps to link back to a Body of Knowledge, such as the [https://gistbok.ucgis.org/ Body of Knowledge for Geographic Information Science and Technologies (GIS&T)]. | |
| − | |||
| − | == | + | ==QGIS Documentation== |
QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. In February 2019 QGIS put out their long-awaited 3.4 Long Term Release, which was a major update from the previous 2.18 version. As of March 2019, the project’s documentation hasn’t fully updated been to the new version. <span style="color:#000000;">Some further ideas discussed during the recent A Coruña Hackfest are:</span> | QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. In February 2019 QGIS put out their long-awaited 3.4 Long Term Release, which was a major update from the previous 2.18 version. As of March 2019, the project’s documentation hasn’t fully updated been to the new version. <span style="color:#000000;">Some further ideas discussed during the recent A Coruña Hackfest are:</span> | ||
| − | |||
<span style="color:#000000;"><nowiki>* Pyqgis cookbook code snipped are now automatic tested, meaning that every new contribution</nowiki></span> | <span style="color:#000000;"><nowiki>* Pyqgis cookbook code snipped are now automatic tested, meaning that every new contribution</nowiki></span> | ||
| Line 93: | Line 92: | ||
<span style="color:#000000;"><nowiki>* Cleaning the isse tracker in github (> 400 issue now) in many different ways:</nowiki></span> | <span style="color:#000000;"><nowiki>* Cleaning the isse tracker in github (> 400 issue now) in many different ways:</nowiki></span> | ||
| − | <span style="color:#000000;">verifying issues, closing duplicates, make order in the labels, etc</span>This is a great opportunity to:# | + | <span style="color:#000000;">verifying issues, closing duplicates, make order in the labels, etc</span>This is a great opportunity to: |
| − | # | + | # Help document a great project. |
| − | # | + | # Update older documentation. |
| − | # | + | # Tap into a very engaged community. |
| − | # | + | # Review against best writing practices and suggest improvements. |
| − | + | # Test best practice writing principles which can be exported and shared with other open source projects. | |
| − | |||
| − | * | + | * Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS |
| − | * | + | * Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here [https://qgis.org/test/en/ https://qgis.org/test/en/]. |
| − | * | + | * Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement |
| − | * | + | * Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc |
| + | Resources: | ||
| + | * [https://www.qgis.org/en/docs/index.html QGIS Documentation] | ||
| + | * [https://github.com/qgis/QGIS-Documentation/issues QGIS Documentation Issues] | ||
| + | * [http://spatialquerylab.com/foss4g-academy-curriculum/ University-level lectures and labs, created by GeoAcademy] (based on the older QGIS 2.18) | ||
| + | ==Other OSGeo Project Docs == | ||
| − | + | TBD: Are there other projects that are at a tipping point - that could achieve the QGIS momentum if they get a push? | |
| − | |||
| − | |||
| − | + | ==Improve OSGeoLive writing instructions== | |
| − | |||
| − | == | ||
| − | |||
| − | |||
| − | |||
| − | |||
We’ve recently updated our OSGeoLive process for generating documentation, and have moved our documentation repository from MediaWiki to trac. We appear to have introduced a few gaps in the move. In particular, the new docs don’t reference our specific writing instructions which are embedding in [https://raw.githubusercontent.com/OSGeo/OSGeoLive-doc/master/doc/overview/postgis_overview.rst Project Overview] and [https://raw.githubusercontent.com/OSGeo/OSGeoLive-doc/master/doc/quickstart/udig_quickstart.rst Quickstart] reference documents. A nice discrete task would be to review the old and new processes, and update the new docs to ensure they still contain relevant information, and are easy to follow. | We’ve recently updated our OSGeoLive process for generating documentation, and have moved our documentation repository from MediaWiki to trac. We appear to have introduced a few gaps in the move. In particular, the new docs don’t reference our specific writing instructions which are embedding in [https://raw.githubusercontent.com/OSGeo/OSGeoLive-doc/master/doc/overview/postgis_overview.rst Project Overview] and [https://raw.githubusercontent.com/OSGeo/OSGeoLive-doc/master/doc/quickstart/udig_quickstart.rst Quickstart] reference documents. A nice discrete task would be to review the old and new processes, and update the new docs to ensure they still contain relevant information, and are easy to follow. | ||
| − | Resources:* | + | Resources: |
| − | * | + | * [https://wiki.osgeo.org/wiki/OSGeoLive_AddProject#Documentation Old, OSGeoLive documentation processes] |
| + | * [https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20a%20project New (incomplete) processes] | ||
| − | == | + | ==New OSGeoLive Quickstarts and Overviews:== |
For our 2019 OSGeoLive release we hope to attract a number of projects which have recently signed up as OSGeo Foundation Community projects. These projects will need help writing their Project Overviews and Quickstarts. Existing project documentation also needs to be updated to align with the latest releases. (Reviewing 50 Quickstarts to ensure they still work is a time-consuming exercise). | For our 2019 OSGeoLive release we hope to attract a number of projects which have recently signed up as OSGeo Foundation Community projects. These projects will need help writing their Project Overviews and Quickstarts. Existing project documentation also needs to be updated to align with the latest releases. (Reviewing 50 Quickstarts to ensure they still work is a time-consuming exercise). | ||
| − | Resources:* | + | Resources: |
| − | * | + | * Ask OSGeoLive team about which new projects are joining OSGeoLive |
| − | * | + | * [https://wiki.osgeo.org/wiki/OSGeoLive_AddProject#Documentation Old, OSGeoLive documentation processes] |
| + | * [https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20a%20project New (incomplete) processes] | ||
| − | == | + | ==Simplify OSGeoLive’s doc writing process== |
Like most open source projects, OSGeoLive templates and content have primarily been created by developers (and a few users), without access to the insights provided by trained technical writers and teachers. | Like most open source projects, OSGeoLive templates and content have primarily been created by developers (and a few users), without access to the insights provided by trained technical writers and teachers. | ||
| Line 141: | Line 138: | ||
Johanna Botman explains the challenges our approach has introduced. She started her working career as an English teacher, then moved into IT, website design, and is now uses geospatial software, as a geospatial officer at a local council. She observed: | Johanna Botman explains the challenges our approach has introduced. She started her working career as an English teacher, then moved into IT, website design, and is now uses geospatial software, as a geospatial officer at a local council. She observed: | ||
| − | + | Some of the issues relating to getting started [with writing project documentation] are about bridging the gap between developers and writers. Developers write code in coding tools. They collaborate, they are used to versioning and are at home with unformatted raw text and automation tools. Writers? They work on Windows machines in Word - maybe in Google Docs if they are lucky. They don’t know about running build scripts, running Linux variants, Github, chat programs, HTML, RST formats, wikis and the variants of markup languages. | |
| − | + | It’s one thing to work with the open source software, another to write about it, and a third thing to work out how to write it so that it fits in with the project. It seems as if the developers have created the writing system in a way that they are used to working, not necessarily in a way that works for writers. | |
| − | There are many ways we can help solve this problem, from small to large:* | + | There are many ways we can help solve this problem, from small to large:* Technical writers can try using our existing writing guides, and document anything that is difficult to understand, and help us fix it. |
| − | * | + | * We can revisit and potentially improve the tools and processes we use. [https://www.gitbook.com/ Gitbook] looks promising. We have already adopted [https://www.transifex.com/ Transifex] for translations. Some research into options and what others are doing would help here. |
| − | * | + | * Processes, tools and howto-write guides could both draw from international initiatives, and if we find ourselves to be world leading, then we should feed our insights back into international best practices. |
| − | == | + | ==Define an authoritative style guide== |
It would be great if there was a compact, authoritative style guide (with different configurations), which could be selected in a similar manner to the [https://creativecommons.org/choose/ selection of a Creative Commons license]. It should be freely available, and coordinated by a non-profit community. (One version might be too idealistic, maybe we need a few). | It would be great if there was a compact, authoritative style guide (with different configurations), which could be selected in a similar manner to the [https://creativecommons.org/choose/ selection of a Creative Commons license]. It should be freely available, and coordinated by a non-profit community. (One version might be too idealistic, maybe we need a few). | ||
| − | Benefits provided:* | + | Benefits provided: |
| − | * | + | * Reduced time learning and maintaining multiple style guides. |
| − | * | + | * Improved documentation quality and consistency, resulting in improved reader comprehension. |
| − | * | + | * Easier for writing tools to support the guide(s). |
| + | * Make it easier for projects to set and apply writing standards. | ||
| + | Resources: | ||
| + | * [https://developers.google.com/style/ Google developer documentation style guide]. | ||
| + | * [https://docs.geoserver.org/latest/en/docguide/style.html GeoServer style guide] (also referenced by GeoNode) | ||
| + | * The Australian government [https://www.themandarin.com.au/102797-the-first-new-edition-of-the-commonwealth-style-manual-since-2002-is-in-the-works/?utm_campaign=TheJuice&utm_medium=email&utm_source=newsletter has announced] that we are updating our style guide. [http://cameronshorter.blogspot.com/2019/01/toward-universal-style-manual.html I’ve suggested collaboration]. | ||
| + | * TBD: What other style guides should we mention? | ||
| − | + | ==OSGeoLive to apply a style guide== | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | == | ||
To date, the OSGeoLive team haven’t selected a style guide. It would be good to get advice from technical writers on which we should choose. We potentially should retrospectively clean up our public facing documentation in line with the selected guide. I’m aware there are tools for auto-checking documentation quality. What options are available for open source projects? | To date, the OSGeoLive team haven’t selected a style guide. It would be good to get advice from technical writers on which we should choose. We potentially should retrospectively clean up our public facing documentation in line with the selected guide. I’m aware there are tools for auto-checking documentation quality. What options are available for open source projects? | ||
| − | == | + | ==Open Source Geospatial Introductory Workshop== |
It wouldn’t take much to create a practical 3-hour introductory workshop introducing ~ six to eight of the leading Open Source geospatial applications. It would be a valuable contribution to many spatial conferences. It could use the existing OSGeoLive distribution along with installed data, and can draw upon existing Quickstarts. | It wouldn’t take much to create a practical 3-hour introductory workshop introducing ~ six to eight of the leading Open Source geospatial applications. It would be a valuable contribution to many spatial conferences. It could use the existing OSGeoLive distribution along with installed data, and can draw upon existing Quickstarts. | ||
| Line 175: | Line 172: | ||
The workshop should make use of best practice template structure for presenting, and set up a template which can be expanded out to other OSGeo projects. | The workshop should make use of best practice template structure for presenting, and set up a template which can be expanded out to other OSGeo projects. | ||
| − | Resources:* | + | Resources: |
| − | * | + | * [http://live.osgeo.org/en/overview/overview.html OSGeoLive Quickstarts]. |
| − | + | * Nicolas Roelandt, Astrid Emde are proposing such a workshop for the Free and Open Source for Geospatial conference (FOSS4G). | |
| − | |||
| − | == | + | ==Define an authoritative Code of Conduct== |
Most conferences and open source communities adopt a Code of Conduct and/or a Diversity Statement. It would be great of the multiple variants were consolidated, and selectable via a tick-box selection process, (like the [https://creativecommons.org/choose/ selection of a Creative Commons license]). | Most conferences and open source communities adopt a Code of Conduct and/or a Diversity Statement. It would be great of the multiple variants were consolidated, and selectable via a tick-box selection process, (like the [https://creativecommons.org/choose/ selection of a Creative Commons license]). | ||
| − | Resources:* | + | Resources: |
| − | * | + | * I [https://wiki.osgeo.org/index.php?title=Diversity&oldid=84020 reviewed numerous Code of Conducts] when co-authoring the [https://www.osgeo.org/code_of_conduct/ The OSGeo Foundation’s Code of Conduct]. |
| + | * [https://www.contributor-covenant.org/ Contributor Covenant Code of Conduct], which has attracted a lot of projects. | ||
| − | == | + | ==Jupyter Notebooks as an OSGeoLive documentation type== |
Jupyter Notebook is a web application that allows you to create and share documents that contain live code, equations, visualizations and explanatory text. It is a useful communication medium for explaining technical concepts. We included Jupyter Notebooks on prior OSGeoLive releases, but we didn’t have a maintainer to bring the documentation up to the standards we expect for OSGeoLive documents. | Jupyter Notebook is a web application that allows you to create and share documents that contain live code, equations, visualizations and explanatory text. It is a useful communication medium for explaining technical concepts. We included Jupyter Notebooks on prior OSGeoLive releases, but we didn’t have a maintainer to bring the documentation up to the standards we expect for OSGeoLive documents. | ||
| − | It would be good to:# | + | It would be good to: |
| − | # | + | # Have Project Overviews and Quickstarts updated to <span style="color:#000000;">could be good to have this standards well explained somewhere</span>our quality standards, so we can re-introduce Jupyter Notebooks. |
| + | # Consider using Jupyter Notebooks as another documentation type supported by OSGeoLive - which would mean developing templates for its use by other OSGeo projects, and attracting maintainers from these projects to create material. | ||
| − | Resources:* | + | Resources: |
| − | * | + | * OSGeoLive 11.0 was the latest release which includes [https://live.osgeo.org/archive/11.0/en/overview/jupyter_overview.html Jupyter Notebook docs] |
| + | * [https://github.com/OSGeo/OSGeoLive-Notebooks OSGeoLive repository of Jupyter Notebooks] | ||
| − | == | + | ==Tweak the OSGeoLive Presentation== |
We maintain [https://live.osgeo.org/en/presentation.html#/ a lightning presentation of the ~ 50 projects on OSGeoLive]. It is a challenge to keep this presentation concise enough to fit within a conference presentation time-slot and could do with tweaking. | We maintain [https://live.osgeo.org/en/presentation.html#/ a lightning presentation of the ~ 50 projects on OSGeoLive]. It is a challenge to keep this presentation concise enough to fit within a conference presentation time-slot and could do with tweaking. | ||
Revision as of 05:58, 10 April 2019
From simple to grandiose writing tasks which will improve OSGeo projects, and open source in general. It includes ideas and first steps for tech writers, software users and those participating in Google’s Season-of-Docs.
We, the communities behind the OSGeo Foundation’s open source geospatial projects, are positioned to help solve big documentation challenges faced by all open source projects. We can achieve this by continuing as we are doing now, with ordinary people, gifting bursts of effort, toward small, discrete and achievable tasks, to collectively achieve an extraordinary impact.
Leveraging Google’s Season-of-Docs
Google’s Season-of-Docs is an initiative to bring open source and technical writer communities together to write documentation. We propose we use this initiative as a focal point to attract a collaborative community to pilot big ideas. In particular:
- Open source projects face sustainability challenges. How will docs developed during Season-Of-Docs be maintained long term?
- Can a writer’s expertise be amplified to help community users and developers write good docs more effectively and efficiently?
- Could best practices developed in one project be applied to the greater open source eco-system?
We propose to focus on one (or more) writing initiatives, for one of our leading OSGeo projects. Goals should focus on:
- Being directly applicable for the project.
- Be captured as a template, which can be easily applied to other OSGeo projects. Ideally this will grow into an initiative which is of value to all open source projects.
- Engages a Season-of-Docs sponsored writer, along with volunteers from project and writing communities.
Key roles sought
- Mentor: As an experienced project team member, provide technical mentorship toward a writing initiative.
- Writer: As someone keen to give back to open source through docs, volunteer to be mentored and tackle our OSGeo writing initiatives.
- Senior writer: Drive the writing aspects of an initiative, including empowering other participants. (Eligible for a stipend from Google).
- Learning expert: Help shape documentation templates and guides by linking back to educational theory. (This role is highly prized).
- Administrator: As an engaged OSGeo community member, act as a Season-of-Docs administrator.
Interested?
If you are considering helping, or maybe just want to learn a bit more, then please reach out to us on our email list. If keen, then add yourself to the list below. (Be concise: Name, brief background, how you’d like to contribute.)
People keen to take part
- Cameron Shorter: Geospatial business analyst. Co-founder of OSGeoLive. Co-editor of OSGeoLive doc templates; reviewer of most of the 50 Project Overview and Quickstart documents. Ex-board member of OSGeo Foundation. Keen to provide connections to our community and to be practically involved in writing initiatives.
- Astrid Emde: Senior GIS consultant at WhereGroup in Bonn, Germany. OSGeo board member and secretary. Awarded the Sol Katz award for leadership and longtime contributions to open source geospatial communities. Contributor to OSGeoLive, the OSGeo marketing committee and co-coordinator of meetups, code-sprints, and the annual German-speaking open source geospatial conference. She likes documentation and teaching people OSGeo Software. Keen to provide connections to our community and to be practically involved in writing initiatives.
- Johanna Boltman: Ex-English teacher, IT admin, and user of open source software as a geospatial officer at a local council. Keen to be mentored in writing docs.
- Belinda Baker: Background in writing process documentation and user of open source software as a GIS Consultant at a software company. Keen to be mentored in writing docs.
- Liam Turner: GIS Specialist for NSW Government (Australia), previously a high school physics teacher. User of open source technical documentation, keen to make a contribution.
- Nicolas Roelandt: Geospatial engineer at the French Institute of Science and Technology for Transport, Development and Networks. OSGeo charter member and OSGeoLive Project Steering Committee (PSC) member. Works on OSGeoLive documentation and translation build process (using the Transifex platform). Keen to support others in the use of these tools.
- Luca Delucchi: Geographer; OSGeo and Open Street Map contributor and advocate. Core developer and translator of the GRASS GIS project; main developer of pyModis library; OSGeoLive and ZOO-Project contributor; president of the Italian OSGeo local chapter. Willing to help improve Jupyter interactive notebook documents in line with a developed template and writing instructions, if one is developed and committed to.
- Nick Bearman: Teaching Fellow in Geospatial Analysis (University College London) and GIS Trainer & Consultant (Geospatial Training Solutions). Contributed to QGIS documentation. Write and deliver GIS training courses to a variety of participants. Keen to learn how to contribute more effectively, particularly to QGIS documentation. Also looking to run a workshop on how to contribute to open source documentation at upcoming FOSS4G UK event in Edinburgh, UK in September 2019.
- Sergio Acosta y Lara: Architect (Universidad de la República/UdelaR) working with Geographic Information Technologies for nearly 30 years. In charge of the Department of Geomatics (Ministry of Transport and Public Works) and member of several Working Groups for Technical Specifications of the IDEuy (Spatial Data Infrastructure of Uruguay). Charter Member of the OSGeo Foundation (Open Geospatial Foundation) and member of the Advisory Board of the Geo4all initiative, Regional chair for Iberoamerica and co-editor of its newsletter. Coordinator for gvSIG Batoví (design and development of a GIS applied to educational environments for the Plan Ceibal (OLPC initiative for Uruguay) based on gvSIG. Co-coordinator of the gvSIG Uruguay Community (web) and of its blog.
- <add your name here>
The back story
For background on the value of communicators, along with ideas on the sort of communities that have proven to be successful in the past, we suggest starting with this article on inspiring techies to become great writers.
Ideas
Best practice templates
Good documentation benefits from access to cross-disciplinary skills. Expertise is typically spread across developers, users, domain experts, teachers, technical writers, graphic artists, and translators. Ramp-up time is high for any group attempting to learn another’s skill-set. This creates a significant barrier to entry.
Our OSGeoLive initiative has achieved sustained, cross-domain collaboration by capturing writer’s expertise within templates with clear and punchy writing instructions. These templates were then provided to developers and domain experts. By using an outline/write/review/translate/publish process we’ve achieved significant efficiencies by allowing experts to focus only on the areas they know best. However, OSGeoLive has only tackled the Project Overview and Quickstarts. Projects which have tacked harder documentation types haven’t addressed cross-project consistency.
How can we align our OSGeoLive writing initiatives with other projects and help build best practice templates for key documentation types? This will be valuable if addressed at an OSGeo level. It will be significantly more valuable if extended to an international, cross-domain level. (It will be challenging to attract momentum, but good groundwork is in place, and if implemented it would have a huge positive impact.)
Potential resources:
- Daniele Procida’s What nobody tells you about documentation.
- Nearme writing templates with accompanying blog post.
- Document type definitions.
- Writing instructions for OSGeoLive Project Overviews and Quickstarts.
- The Write-The-Docs community are a likely source of potential co-contributors and defacto owners of such templates.
- Bloom’s Taxonomy: Teacher Planning Kit is helpful for selecting language for training.
- Someone has suggested ISO standards, but you need to pay to use them, and they appear overly verbose: ISO/IEC/IEEE 26511, 25612, 25613, 25614, 25615.
Other doc types for OSGeoLive
To date, our OSGeoLive community have been sustainably maintaining two of the easier documentation types: Project Overviews and Quickstarts. Established OSGeo projects also have documentation, in various stages of currency, completion, relevance, verbosity, and quality.
I believe we are ready to extend our consistency and best practices to some of the harder documentation types - such as tutorials, workshops and howtos. We should start by focusing on one of OSGeo’s flagship projects, such as QGIS or PostGIS. Join the project’s existing documentation initiatives. Provide feedback and improvements as required. Build templates and writing instructions which can be adopted by other projects. Integrate these with the OSGeoLive publishing and translation pipeline.
Resources:
- To help position training with other courses, it helps to link back to a Body of Knowledge, such as the Body of Knowledge for Geographic Information Science and Technologies (GIS&T).
QGIS Documentation
QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. In February 2019 QGIS put out their long-awaited 3.4 Long Term Release, which was a major update from the previous 2.18 version. As of March 2019, the project’s documentation hasn’t fully updated been to the new version. Some further ideas discussed during the recent A Coruña Hackfest are:
* Pyqgis cookbook code snipped are now automatic tested, meaning that every new contribution
will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
* We have an idea to change the doc style to the more readable RTD vanilla theme
(fully supported by sphinx). A live example `here <https://qgis.org/test/en/>`_
* Besides from contents, writing documentation isn't easy because of the complex
framework (sphinx, git, github, etc). Improving the github editor (wysiwyg)
would be a great enhancement
* Cleaning the isse tracker in github (> 400 issue now) in many different ways:
verifying issues, closing duplicates, make order in the labels, etcThis is a great opportunity to:
- Help document a great project.
- Update older documentation.
- Tap into a very engaged community.
- Review against best writing practices and suggest improvements.
- Test best practice writing principles which can be exported and shared with other open source projects.
- Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
- Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
- Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
- Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
Resources:
- QGIS Documentation
- QGIS Documentation Issues
- University-level lectures and labs, created by GeoAcademy (based on the older QGIS 2.18)
Other OSGeo Project Docs
TBD: Are there other projects that are at a tipping point - that could achieve the QGIS momentum if they get a push?
Improve OSGeoLive writing instructions
We’ve recently updated our OSGeoLive process for generating documentation, and have moved our documentation repository from MediaWiki to trac. We appear to have introduced a few gaps in the move. In particular, the new docs don’t reference our specific writing instructions which are embedding in Project Overview and Quickstart reference documents. A nice discrete task would be to review the old and new processes, and update the new docs to ensure they still contain relevant information, and are easy to follow.
Resources:
New OSGeoLive Quickstarts and Overviews:
For our 2019 OSGeoLive release we hope to attract a number of projects which have recently signed up as OSGeo Foundation Community projects. These projects will need help writing their Project Overviews and Quickstarts. Existing project documentation also needs to be updated to align with the latest releases. (Reviewing 50 Quickstarts to ensure they still work is a time-consuming exercise).
Resources:
- Ask OSGeoLive team about which new projects are joining OSGeoLive
- Old, OSGeoLive documentation processes
- New (incomplete) processes
Simplify OSGeoLive’s doc writing process
Like most open source projects, OSGeoLive templates and content have primarily been created by developers (and a few users), without access to the insights provided by trained technical writers and teachers.
Johanna Botman explains the challenges our approach has introduced. She started her working career as an English teacher, then moved into IT, website design, and is now uses geospatial software, as a geospatial officer at a local council. She observed:
Some of the issues relating to getting started [with writing project documentation] are about bridging the gap between developers and writers. Developers write code in coding tools. They collaborate, they are used to versioning and are at home with unformatted raw text and automation tools. Writers? They work on Windows machines in Word - maybe in Google Docs if they are lucky. They don’t know about running build scripts, running Linux variants, Github, chat programs, HTML, RST formats, wikis and the variants of markup languages.
It’s one thing to work with the open source software, another to write about it, and a third thing to work out how to write it so that it fits in with the project. It seems as if the developers have created the writing system in a way that they are used to working, not necessarily in a way that works for writers.
There are many ways we can help solve this problem, from small to large:* Technical writers can try using our existing writing guides, and document anything that is difficult to understand, and help us fix it.
- We can revisit and potentially improve the tools and processes we use. Gitbook looks promising. We have already adopted Transifex for translations. Some research into options and what others are doing would help here.
- Processes, tools and howto-write guides could both draw from international initiatives, and if we find ourselves to be world leading, then we should feed our insights back into international best practices.
Define an authoritative style guide
It would be great if there was a compact, authoritative style guide (with different configurations), which could be selected in a similar manner to the selection of a Creative Commons license. It should be freely available, and coordinated by a non-profit community. (One version might be too idealistic, maybe we need a few).
Benefits provided:
- Reduced time learning and maintaining multiple style guides.
- Improved documentation quality and consistency, resulting in improved reader comprehension.
- Easier for writing tools to support the guide(s).
- Make it easier for projects to set and apply writing standards.
Resources:
- Google developer documentation style guide.
- GeoServer style guide (also referenced by GeoNode)
- The Australian government has announced that we are updating our style guide. I’ve suggested collaboration.
- TBD: What other style guides should we mention?
OSGeoLive to apply a style guide
To date, the OSGeoLive team haven’t selected a style guide. It would be good to get advice from technical writers on which we should choose. We potentially should retrospectively clean up our public facing documentation in line with the selected guide. I’m aware there are tools for auto-checking documentation quality. What options are available for open source projects?
Open Source Geospatial Introductory Workshop
It wouldn’t take much to create a practical 3-hour introductory workshop introducing ~ six to eight of the leading Open Source geospatial applications. It would be a valuable contribution to many spatial conferences. It could use the existing OSGeoLive distribution along with installed data, and can draw upon existing Quickstarts.
The workshop should make use of best practice template structure for presenting, and set up a template which can be expanded out to other OSGeo projects.
Resources:
- OSGeoLive Quickstarts.
- Nicolas Roelandt, Astrid Emde are proposing such a workshop for the Free and Open Source for Geospatial conference (FOSS4G).
Define an authoritative Code of Conduct
Most conferences and open source communities adopt a Code of Conduct and/or a Diversity Statement. It would be great of the multiple variants were consolidated, and selectable via a tick-box selection process, (like the selection of a Creative Commons license).
Resources:
- I reviewed numerous Code of Conducts when co-authoring the The OSGeo Foundation’s Code of Conduct.
- Contributor Covenant Code of Conduct, which has attracted a lot of projects.
Jupyter Notebooks as an OSGeoLive documentation type
Jupyter Notebook is a web application that allows you to create and share documents that contain live code, equations, visualizations and explanatory text. It is a useful communication medium for explaining technical concepts. We included Jupyter Notebooks on prior OSGeoLive releases, but we didn’t have a maintainer to bring the documentation up to the standards we expect for OSGeoLive documents.
It would be good to:
- Have Project Overviews and Quickstarts updated to could be good to have this standards well explained somewhereour quality standards, so we can re-introduce Jupyter Notebooks.
- Consider using Jupyter Notebooks as another documentation type supported by OSGeoLive - which would mean developing templates for its use by other OSGeo projects, and attracting maintainers from these projects to create material.
Resources:
- OSGeoLive 11.0 was the latest release which includes Jupyter Notebook docs
- OSGeoLive repository of Jupyter Notebooks
Tweak the OSGeoLive Presentation
We maintain a lightning presentation of the ~ 50 projects on OSGeoLive. It is a challenge to keep this presentation concise enough to fit within a conference presentation time-slot and could do with tweaking.