Last Friday, the documentation team ran a training session for 25 odd newcomers to open source contribution. While the silence in response to “How many of you have ever contributed to any open source project?” was deafening, it was refreshing to see so many people turn up to try something new and the enthusiasm was overwhelming.
Many of the attendees came with GNOME in a virtual machine or installed, as we asked them to make sure that they had a recent version or gnome-continuous in a VM, which is essential for documentation. While most of the attendees were running Unity or GNOME, some were running Windows.
The tools which the newcomers had to have were a text editor, git and yelp. yelp-tools was also desirable, but although we covered yelp-tools briefly, we didn’t get around to using it.
The newcomers started by finding the GNOME documentation team space on the wiki and navigating to the tasks page. While they would normally have been expected to pick the link to easy bugs from there, for the training session, we picked some bugs that had especially low barriers to entry. These bugs did not generally require one to build applications, had especially good descriptions and were relatively clear.
When the newcomers reached Bugzilla and picked a bug, the next step was to figure out which project the help was in (gnome-user-docs or one of the applications, this is listed under “Product” in the bug details), then find the product in git. One of the issues which we came across was that the search for git repositories is a little bit unreliable. For example, searching for “gnome user docs” gives no results, instead of showing gnome-user-docs. While I would generally start a browser search for the repository name on the page, almost all the newcomers went straight for the search field in the page.
Next up, the newcomers had to understand the bug, and in some cases find which page it was on. While the majority of user docs are in /help/C, it was very confusing that gnome-user-docs are in /gnome-help/C. And why not help/en? C is intended to be the source docs, and it’s only convention that they happen to be in English in GNOME. There’s no reason for them to be in English other than that more people are able to write in English and translate from English.
Files were edited, changes were made. Various text editors were used, such as vim, vi, emacs, nano and gedit, to name a few. Files were not always saved.
At this point, it became clear that some parts of the help on how to write documentation could be improved. Eventually, everything was figured out.
As most of the attendees had never used git before, they had to set it up.
Lastly, the patch creation and attaching patches to bugzilla were simple last steps to finish off over an hour of work.
The experience has reinforced the idea that the biggest step to first contributions is setting up the working environment and figuring out how all of our tools work. This is surprisingly difficult for many people who want to contribute and learn how we work.
We had around 25 attendees, some of whom worked in pairs. Unfortunately, it’s currently not possible to have multiple authors for a commit, so some of the newcomers who worked in pairs will not be listed as authors in git. In total, there were around 20 odd bugs that were looked at. André, Dave and Aleksander helped out at the event, but it was still difficult to effectively help so many people. Under ideal circumstances, I would prefer to have an absolute maximum of 4 individuals per mentor and preferably around 3 or so capable attendees per mentor.
