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

G-Cloud 11 Update

Astun Technology have been a Crown Commercial Service (CCS) Approved Supplier for a number of years now, with our solutions and services available via their Digital Marketplace.

Our customers have acquired our solutions via both the G-Cloud and Local Authority Software Applications (LASA) frameworks.

G-Cloud 10 was replaced by G-Cloud 11 on 2 July 2019 and I am delighted to say that all of our solutions and services are now available for purchase under this new framework. This framework makes buying cloud solutions and services faster and cheaper than entering into individual procurement contracts, so switching to Cloud based GIS has just got easier.

Our solutions are available under the Cloud Software and Cloud Support lots as follows:

Cloud Software
iShare In the CloudQGIS in the CloudAstun Data ServicesGet INSPIREdGet INSPIREd and Enterprise Metadata for iShareGet INSPIREd Enterprise
Cloud Support Geospatial Cloud Consultancy ServicesGeospatial Open Source Support PackagesGeospatial O…

Making home working work!

I was chatting to a personal acquaintance recently about work and we got on to the subject of home working. The organisation she worked for was going through a period of change and they were planning on moving some of their office staff to home working on a permanent basis. She was after my views on how we manage to make that work effectively at Astun. This blog, which is very much a manager's perspective, is what I told her!

Before we get on to to the two key themes of this blog - the Technical and Cultural - a quick bit about Astun first! 1. Astun's circumstances We employ around 21 people, of which 6 or so work from an office in Epsom, and the rest work from home on a permanent basis. From my home in Bristol, I line manage 13 of those people, 3 of which are office based, the rest primarily work in the UK, as far north as Tyneside & Lancaster and as far south as Southampton. I have one member of the team who is based in Seville in Spain.
2. Technical Use of technology is k…

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. …