Project Report for Season of Docs 2019

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.

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s