The inaugural Google Season of Docs program ran from March through to November 2019, to bring open source projects and technical writers together. 

My submission was accepted and I worked on a project for the Open Source Geospatial Foundation.

Work description

The Open Source Geospatial Foundation (OSGeo) has a large number of separate open source geospatial software projects. One of their initiatives is called OSGeoLive, which is a self-contained bootable distribution of about 50 open source geospatial projects.

The OSGeoLive projects have Overview and Quickstart documentation. The work I undertook as part of Google Season of Docs was to:

  • Review the Quickstarts to ensure they were current, accurate and relevant.
  • Create a Quickstart template to ensure consistency and to aid future contributors.

The audience for my work included writers of OSGeoLive Quickstarts and end-users of OSGeoLive.

My mentor was Cameron Shorter.

Work done

Proposed

Status

Comments

Review existing OSGeo Live Quickstart guides

Complete

I used the “OSGeo-Live Packages spreadsheet” to track my work.

I reviewed the published Quickstarts and rated them out of 4 according to the presence of the “Overview”, “Things to try” and “What next?” sections, as well as the quality of the procedures and language.

OSGeoLive Packages spreadsheet

Provide a report summarising the outcome

Complete

I created a presentation which summarised the results and provided the scope of work.

QuickStarts Review

Create a Quickstart template to ensure consistency for future

Complete

This is merged into the doc repo.

https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst 

Update the 'How to document the Quickstart file' page

Complete

https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20quickstart%20file

From version 5 to version 12 (latest) changes made by flicstar

Edit the Quickstarts and raise pull requests with edits and suggestions

Complete

Created pull requests in the OSGeoLive-doc repo:  https://github.com/OSGeo/OSGeoLive-doc/

Create companion documentation tickets in trac (Issue tracker)

Complete

Created trac tickets:  Trac ticket report 
(all defects created by flicstar with component=documentation)

Post-program

In recognition of the extra value generated by the Season Of Docs work, and the desire to publish the material before the next major release, a motion was raised on 27th November to do a documentation-only point release (version  13.1). 

Challenges and learnings

  • Be open-minded and flexible.
  • Use the tools that the community uses, and follow their conventions.
  • Be aware of potential for scope creep and how to manage it.
  • Be ready to embrace new opportunities as they arise (which may mean dropping some of the original scope).
  • Be aware of the international nature of the community, and inherent cultural differences.
  • Remember to set your alarm for meetings! 
  • Engaging the community takes time and effort. It can be as time-consuming as doing technical writing work. Allow for this time when planning the project.