Skip to main content

Improving project documentation with a codesprint

Background

 At the end of November I was asked by Francois Prunayre at Titellus to help organise and manage a 3-day code-sprint with the aim of improving GeoNetwork documentation. Documentation can be problematic for projects, even open source, where the majority of the work is done by volunteers. Updating documentation is rarely a priority for developers, who are time-poor and have actual project issues to deal with, and efforts to widen the base of contributors so that others can help, also take time.

Back to the code-sprint

This code-sprint was timed very well though, as it comes on the back of work being done to update GeoNetwork documentation as part of OSGeo's participation in Google's Season of Docs. This pairs a paid technical writer with an open source project for either three or six months, with the aim of seeing a rapid improvement in that project's documentation. I'm an admin and mentor for OSGeo on Season of Docs, so was well-placed to provide input to the code-sprint. As part of the Season of Docs work, we've completed a base-line survey of the documentation, highlighting areas that need improvement, are out of date (usually new features or screenshots) or simply missing. The output was a spreadsheet that participants in the code-sprint could use to assign sections of work, and mark when ready for review or when completed.

Challenges


An interesting thing about this particular code-sprint was that it was entirely remote. Those of us in roughly similar time zones "met" every morning in the GeoNetwork Gitter channel, and decided our intentions for the day. It was trickier for the people based in Australia or the US as their work days didn't really coincide.

A fair amount of preparation was required for participants, in the form of setting up a documentation build environment locally so they could fully test any changes, along with creating a fork of the main GeoNetwork documentation repository. Then there was the learning curve of getting up to speed with the reStructuredText format used for the documentation. This was quite in-depth, and I think might have put a few people off, although we tried to create a comprehensive guide to updating the documentation before we started.

The process of submitting a change wasn't trivial. Having built the documentation locally, participants had to push the change to their fork of the repository, and then make a pull request (PR) to the master or upstream repository (eg the core GeoNetwork one). This had to be reviewed by other participants before being accepted, which in itself was quite time-consuming. Additionally, sometimes different people would submit pull requests that conflicted with each other or cancelled each other out. I tried to get around that with my own fork by using something called a Pull-bot, which monitored my fork for changes in the upstream repository and automatically updated it, but still there were occasional glitches!

Results

I decided it would be a good use of my time to work through the release changelogs and ensure that all the new features and bug fixes in there were included in the documentation if appropriate. If I found something was missing, I created an issue for it - including whether it needed a screenshot, more documentation, or was simply blank. Updated screenshots were easy pickings, but some of the other issues will take a bit longer to work through. This task was more time-consuming than expected, but meant I got a really good overview of the new features, including some I didn't know about! Since we're now up to date with the newest release, it should be quite straightforward to continue this process moving forward.

I also made sure that the section on User Interface configuration was updated, as this has changed substantially in the most recent versions of the software. This took a long time, but was unexpectedly helpful in that I identified a couple of bugs as well as updating the documentation.

Other people bravely took on the task of documenting complex new features such as the workflow enhancements and the improved map viewer. I was asked to review some of these sections before they were incorporated in the live documentation, which again was a great way of learning about new functionality.

All in all, only a few people could spare the time to work solidly on the documentation for the entire three day sprint, but others dropped in and out when they had time. It was pretty successful though, and I think there are plans to repeat the process.

Final thoughts

Documentation is hard, and there's a big on-boarding process in terms of getting started with the build environment, reStructuredText syntax and GitHub workflow. Good documentation for helping new users through this process is vital.

Actually participating in a code-sprint for three solid days is also hard! To make a code-sprint work you need that process absolutely rock solid, with people to review Pull Requests and ensure that they are processed quickly so that participants can see their results reflected in the live documentation. Distributed code-sprints also add problems when participants are in widely different time zones.

I must say that after all the hurdles the code-sprint was a success and it would be great to do again.

Comments

Popular posts from this blog

Reflections on FOSS4G UK Edinburgh 2019

Six members of the Astun team recently headed en mass to the Free and Open Source Software for Geo (FOSS4G) UK conference in Edinburgh - and we came back with a 7th!

FOSS4G is a great forum to find out all the latest on what is going on in the OSGeo community and to spread the word via talks and workshops about some of the exciting work we’ve been involved in. Check out the post to find out about our own personal reflections of the event … and find out who our latest recruit is in the final post!

Dan The FOSS4G UK conference just seems to get better and better each year, and this year was no exception. As the baton gets passed annually to a new organising team, the advice and guidance on running a great event goes with it. This year’s team led by co-chairs Tom Armitage and Ross McDonald did an amazing job. The venue was breathtaking, the agenda was packed with outstanding talks and workshops and the atmosphere both during the day and in the evening social just had a great buzz to it. …

Wychavon District, Malvern Hills District, and Worcester City councils sponsor improvements to the Gemini metadata plugin for Geonetwork

Astun have been working with Wychavon District, Malvern Hills District and Worcester City councils on some improvements to the Gemini 2.2 Metadata Plugin for Geonetwork.

The councils approached us at one of our User Group events in 2018 for some assistance with their joint data and metadata publishing workflow. In this workflow, data is published as WMS and WFS using Geoserver. Metadata in the WMS and WFS responses are harvested by Geonetwork to create metadata records, which are then published to data.gov.uk. The goal was to create fully valid Gemini 2.2 metadata directly from Geoserver, without the need for editing the records in Geonetwork. We worked with the councils to establish that the Geoserver INSPIRE plugin and built-in metadata tools met most of that requirement, but that some elements were either incorrectly added or missing entirely when the metadata was harvested into Geonetwork.

Astun have enhanced the Gemini 2.2 metadata plugin for Geonetwork to improve it's WMS an…

FOSS4G UK Edinburgh 2019

This year, Astun staff are giving 4 presentations and 1 workshop at FOSS4G UK Edinburgh to share with the community what we are passionate about as individuals, and as an organisation. At Astun we believe that we are the 'Experts in Place', but to live up to this claim we must do everything but stay 'in place' by constantly evolving what works, and revolutionising what doesn't. With that in mind, here's a preview of the presentations we're giving next month:
Matt Walker; OpenLayers Workshop The OpenLayers (OL) Workshop will guide attendees through the official Workshop material, providing a comprehensive overview of OL as a web mapping solution. The workshop format follows a series of modules covering everything from the basics of creating an OL map, through to specific functionality such as handling vector data, and building content for consumption on mobile devices.

We will work through as many of these modules as we have time for! The workshop material is…