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.