Season of Docs Ideas 2019

OSGeo's Season of Docs home page.

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 small bursts of effort, toward 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. The OSGeo Foundation will be allocated one paid tech writer, which we are [#People_keen_to_take_part matching with multiple volunteers]. 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.

Key roles sought

Our OSGeo foundation can absorb many more writers than the one writer who will be paid by Google. Want to join us?

• Volunteer Writer: As someone keen to give back to open source through docs, volunteer to work with like-minded people. Mentor and be mentored. Tackle anything from simple fixes through to world-leading thought leadership.
• Volunteer Technical Mentor: As an experienced project team member, provide technical mentorship toward a writing initiative.
• Volunteer Learning Expert: Help shape documentation templates and guides by linking back to educational theory. (This role is highly valued).
• Volunteer Administrator: As an engaged OSGeo community member, act as a Season-of-Docs administrator.
• Paid Senior Writer: Lead the writing aspects of our initiative, including empowering other participants. Selection Criteria.

Interested?

If you are considering volunteering, 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

1. Cameron Shorter [Admin and Mentor]: 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.
2. Jo Cook [Admin and Mentor]: Geospatial Consultant and metadata lead at Astun Technology. Chair and founder of the OSGeo UK Local Chapter, chair of FOSS4GUK 2016, vice-chair of FOSS4G 2013, and previous OSGeo board member. Keen to mentor technical writers and generally reduce the barriers for non-coders to contribute to projects, using documentation as a way in.
3. Matteo Ghetta [Admin and Mentor]: Geospatial Software Developer, Writer, and Trainer with Faunalia consulting company in Italy. QGIS doc team coordinator, as well as being sponsored to upgrade docs, such as upgrading training manual to QGIS version 3.x, and writing processing algorithm help files.
4. María Arias de Reyna [Mentor]: GeoNetwork maintainer. President of OSGeo Foundation. Open Source Advocator and Women in Technology activist. Software Engineer with more than a decade of experience in the spatial field. I would like to mentor someone to improve GeoNetwork documentation to make sure both users and developers have a good reference manual.
5. Nick Bearman [Mentor]: 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.
6. Astrid Emde [Mentor]: 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.
7. Nicolas Roelandt [Mentor]: 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.
8. 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.
9. Andrew Jeffrey: Spatial Consultant in Bathurst, NSW, Australia, involved in QGIS training and support. Involved in the Australian QGIS user group, have contributed to QGIS documentation, and have a keen interest in improving the community and access to information for users. Out of the Google Summer of Docs, I am interested in being mentored to improve my QGIS documentation contributions, and learn of any best practices that can facilitate a good delivery of information.
10. Adam Steer: Independent geospatial consultant, scientist, community builder. Board member of OSGeo Oceania; charter member of OSGeo and OGC representative. Sometimes occupying all the chairs of coder/writer/analyst/manager - sometimes all at once; keen to contribute my experience to both document and training material writing; and mentoring new contributors. Also keen to learn and improve my own practices in contributing to OSGeo projects.
11. 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.
12. 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.
13. 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.
14. Sara Ratner: MEd (Masters of Education). Researched, developed and embedded educational theory in school, tertiary and corporate contexts. PhD Candidate at the University of Melbourne, Australia, exploring the automation of industry / future of work and its impact on the purpose of schooling. Keen to contribute toward building documentation templates which link back to educational theory and absorbing information effectively.
15. Phillip Davis: Professor of Computer Science in Corpus Christi, Texas USA. Longtime open source geospatial advocate, rabble-rousing troublemaker all over the world. Project manager and maniac behind the 2012-2015 build of the US GeoAcademy. Created five Massive Open Online Courses (MOOC) as project manager and major funder from the US National Science Foundation (NSF) and US Departement of Labour (DOL). Interested in helping to promote and develop any geospatial open source educations resource. Potential NSF and DOL US Federal grant writer and Principal Investigator.
16. Charlie Schweik: Professor of Environmental Conservation and Public Policy, University of Massachusetts, Amherst. Advocate of open educational resources and continues to be interested in developing collective action in GeoForAll and OSGeo toward developing a collaborative effort around educational materials. I'd welcome the opportunity to mentor somebody (especially if there were from my university) to write for this effort.
17. Chris Pettit: Professor of Urban Science, City Futures Research Centre, Faculty of Built Environment, University of New South Wales (UNSW) Sydney, Australia. Advisory Board member for the OSGeo GeoforAll initiative and open source advocate. Passionate about how city analytics can support smart city planning and policy-making. Interested to mentor a writer in developing open source geospatial education materials relevant to city analytics and data-driven decision making to support the realization of sustainable, productive, smart, resilient and liveable cities.
18. Piers Higgs: CEO Gaia Resources. Interested in contributing our Environmental QGIS training course toward QGIS writing initiatives, and also to provide a little mentorship toward future development of this and related material.

• ... add your name here

Selection criteria for paid role

For the paid senior technical writer role, we are looking for someone to help us reach our goals of being impactful, sustainable and effective.

About you:

• You likely have had years of experience working as a senior technical writer or equivalent. You are familiar with various style guides, writing styles, information design, writing tools, etc.
• It will be helpful if you understand the basics of software development, including:
  • Installing software on Linux, windows and mac, from the command line
  • Using basic git and github functionality to update documentation
  • Writing in wiki, markdown and restructured text formats
• You are motivated by more than the paid stipend. You intend to stick around and amplify the long term impact of your contributions.
• You are nice and friendly, in line with our code-of-conduct.

In responding, consider:

• How will your contributions be valuable beyond the SeasonOfDocs period, beyond the initiative you take on, beyond the specific project(s) you help?
• How will you be helping others become more effective? Look at profiles of volunteers interested so far.
• How would you suggest we shape our communication strategy?
• Will you be able to help us find and then become involved in best practice documentation communities? You might already be part of such communities.
• Google offers standard-length (3 months) and long-running (6 months) options (for the same stipend funds). The longer timeframe is better suited to working with volunteers and our goal of sustainability.
• It will be challenging for us to have the bandwidth to assess whether you are both competent and will sustain your involvement long term. Are you able to reference your volunteer involvement in other communities? How can you concisely reference your communication expertise?
• Involvement in writing communities, such as WriteTheDocs would be considered valuable or worth referencing.

Does all this sound exciting, but you suspect you don’t have the bandwidth or expertise for the paid senior technical writer role? Why not join our volunteers?

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. Geospatial 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 across our all our OSGeo geospatial projects. 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:

• Inspiring great technical docs, using templates. Vision as a presentation - 8 min read.
• Daniele Procida’s What nobody tells you about documentation. (videoed at PyCon 2017).
• 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.
• Nearme writing templates with accompanying blog post.
• 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.
• Words NOT to use in your documentation
• 3 essential components of great documentation
• Twitter thread on good writing that can equally be applied to technical documentation
• Another twitter thread on words to avoid when writing documentation

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

QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. QGIS's core documentation is comprehensive and there is a diverse ecosystem of organisations and people who have created QGIS workshops and training courses. However, it is challenging for documenters to keep up with QGIS’s rapid innovation and to sustainably keep the breadth of documentation current, consistent, and targetted.

Season of Docs ideas for QGIS include:

• Get assistance from writers to create a simple and clear "quickstart".

WHY? Quoting Andrew Jeffrey: "Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost."

• Review the structure of current documentation and provide clear separation of tasks.

WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? A writer could assist with by defining the best practice structure.

• Writers to review the language and readability of the QGIS Step by Step contribution (This is documentation for making documentation contributions).

WHY? This guide walks a user through making a contribution to the QGIS documentation. The process for maintaining documentation probably won't change soon, so let's reduce the contributor’s barrier to entry by making this section so accurate and clear that anyone can pick it up.

• Define a documentation vision, strategy and schedule.

WHY? Quoting Harrissou: "I've been contributing to QGIS docs for years and one thing I miss is ... a direction. What are the priorities? ... [We should better] define schedules, plan when releases should be done. We do it well with the application, it could be nice to have the same for docs."

• Triage and then manage QGIS's documentation issue tracker. Audit the status of QGIS documentation. Publicly share status, strategy, and vision. This will help volunteers know how to engage, and what impact they can provide.

WHY? Quoting Harrissou: "Most of our 400 issue reports are automatically generated by commits in QGIS code so we directly have what we should write about in the doc repo. But this becomes a weakness when:

• there's not enough people to write (increasing number of issues),
• there's no cleanup for duplicate issues (because of backports) or unrelated issues (eg API matters) --- we try to fix these ones
• or the commit message is not clear enough for writers (who may not have the same technical knowledge as the developer). If we can get some clues on how to make devs write more detailed description in noob language, big +1.

I think that triaging the issue tracker and setting priorities and deadlines may greatly help in telling where a senior writer can help (in writing, I mean). I'm not sure any of us (at least me, I do not) have the actual big picture of the issue reports and can categorize them. We already have the necessary tags but now we need to use them. So this would be my task 1."

• Consolidate core QGIS training material

WHY? There are a number of geospatial training courses which cover a range of topics. Merging all these courses into a central source is not practical or desirable. However, there would be value in consolidating basics into a central base. This will be challenging, but valuable, and would require excellent skills in coordination, community building, and writing. Some of the content authors are already committed to sharing and supporting such an initiative. Others will likely come on board once momentum grows.

Quoting Jo Cook: "I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area."

• Develop some modular "open educational resource" (OER) training material (e.g., lab exercises) that can be rapidly adopted by faculty in universities to help them with their courses. This could be especially helpful for new, junior faculty in geography, geosciences, or other fields where they are being asked to create and teach new course preparations in the early days of their career and also trying to build and develop their research programs. Having available open access material and available datasets for adoption could lead to rapid adoption. Once a faculty develops a first cut at a course, that content is often used for many years afterward. It would be useful to identify some standard courses that new faculty might be trying to build. A decision would need to be made on the correct Creative Commons license (I'd vote for CC BY-SA -- Attribution-Share-Alike).

• The Geoacademy group did this for several courses and perhaps contacting them and seeing if that material can be updated (if needed), and made modular -- think buffet style for instructors to pick and choose labs for their courses -- could be a good set of content for a start. Introduction
• Other, more advanced lab modules could be helpful too, particularly in areas such as advanced spatial analysis methods or new and quickly growing areas. I'm in the process of developing material for an Applications in Unmanned Aerial Systems course (geared toward use for environmental management). I have 5-6 labs and data already developed and they use QGIS. I'd welcome another collaborator on this in an effort to develop a specialized set of lab modules or an OSGeo published lab manual and data on UAS-based data analysis. -- Charlie Schweik

Resources:

• QGIS Documentation
• QGIS Documentation Issues
• Contribute to QGIS Docs - Notes recorded from a contribution
• Perspectives on the state of QGIS docs, from Harrissou, Andrew Jeffrey, Nick Bearman, Jo Cook, Richard Duivenvoorde.
• University-level lectures and labs, created by GeoAcademy (based on the older QGIS 2.18)
• Environmental QGIS training and videos from Gaia Resources (based on the older QGIS 2.18)
• Andrew Jeffry's additional tips for newbie QGIS writers

GeoNetwork

GeoNetwork is the leading open source metadata catalog for spatial data, and is an OSGeo Foundation project. It has read-the-docs style documentation separated by user, administrator, maintainer, and contribution guides. There is additional documentation within the GeoNetwork source code that could be replicated or incorporated into the main documentation. Documentation is primarily written by developers, many who have English as a second language. Consequently, there is a great opportunity to improve language, readability and structure.

Documentation hasn't kept up with feature development. Some functionality has dated instructions and screenshots, and in places there is only placeholder text or no documentation at all. This impacts user experience and leads to more questions on our user and developer mailing lists.

We'd like to reduce the barrier to entry to adding documentation. We have started tagging "easy to resolve" issues in our github repository but this has not gained much traction yet.

Season of Docs ideas for GeoNetwork include:

• Geonetwork team to scope and create issues for incomplete documentation (drawing from doc review and pull requests).
• Geonetwork team to reach out to, encourage and support co-contributions to documentation from user base.
• Writer to reorganize documentation to clearly separate user, administrator and developer sections, removing duplicated content.
• Writer to provide templates and writing instructions to help reduce barrier-to-entry and improve quality of developer's contributing content.
• Writers to review language and readability.
• Writers to follow existing quickstarts, upgrade and improve.
• Writers to work through documentation issue list.

Resources:

• Source code of existing docs: https://github.com/geonetwork/doc
• Existing docs: https://geonetwork-opensource.org/docs.html
• Extra developer docs: https://github.com/geonetwork/core-geonetwork/wiki#documentation

Other OSGeo Project Docs

There are 50+ open source geospatial (OSGeo) projects which are related and good candidates for joining this initiative.

Resources:

• OSGeoLive list of ~ 50 Project Overviews and Quickstarts, along with activity metrics
• OSGeo UN Education Challenge:
  • Update training material for PostGIS and other applications
  • Timeframe: May - Dec 2019, (work between August and November)

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:

• Old, OSGeoLive documentation processes
• 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).

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:

1. Have Project Overviews and Quickstarts updated to our quality standards, so we can re-introduce Jupyter Notebooks.
2. 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.