Documentation, GUADEC and more documentation

Leave a reply

It is traditional for the documentation team try to meet a few times per year for hackfests, alternating between Europe and North America to help the whole team make it to at least one event per year. The hackfests serve two purposes: getting work done and motivating/rejuvenating the team.

This year, we met in Norwich to work on user docs for 3.12, in Berlin for the developer experience hackfest, at GNOME.Asia to guide new contributors to GNOME and at Open Help in Cincinnati for the best documentation conference and lots of awesome improvement to the sysadmin guide. We also hung out together at GUADEC. It’s unfortunate that not all the team members could make it to Open Help and GUADEC.

GUADEC was interesting this year. It was great to meet up with old friends, meet lots of new people (/me looks at Shobha) and new old people who I should have long since met by now. Tarte flambée and whisky were had by all. Hair happened to some. Tea, damsons and mirabelles also happened (shortly after we returned, I found a mirabelle tree in the shared green space across the road from our house). It was nice to see everyone enjoying themselves at the picnic and football. Bastien always wins.

It was a shame to not see as many documentation team members at GUADEC as we’ve had in previous years and the team didn’t really have a proper hackfest either (although we did participate in a screenshot automation BoF). Spending two days in board and adboard meetings isn’t fun, but is necessary and generally much more productive than phone meetings. I was disappointed to see an anti-harassment policy for the conference: it is a shame that it is thought that the community is tending in the direction of harassing behaviour to a point where there is a requirement for the community to enforce the law (harassment and discrimination are illegal in many, if not all, European countries). I want to be part of a community built on mutual respect, not distrust and inability to communicate. It also seems that the policy can only be used by specific individuals, not everyone, which does seem counter-productive.

It seemed to me, having been involved in GUADEC organisation for the last four years, that 2014 was an especially challenging year. I appreciate all the work that Alexandre and the team have put into making it happen. I foresee even more challenges for 2015, but I’m sure that we will all be there to support the new team.

3.14 was a bit of a slow release cycle for documentation as the team as a whole have not had much free time to work on updating it. I would like to thank the translation teams for being awesome and helping out by filing bugs and patches (both of which are very welcome). There are currently rather a lot of documentation patches and branches to review, so I will be concentrating on those in the next few weeks. I hope that the team will be able to hold another hackfest in January or February to prepare for 3.16, but this is currently a bit of an uncertainty unless we can find sponsors to help with travel. If you know of anyone interested in sponsoring the hackfest please get in touch with the team or with me.

Thank you to the GNOME Foundation for sponsoring my travel and accommodation at GUADEC, and to Liam, Ella, Finn and Martin for looking after the chickens. I wouldn’t have been able to make it to GUADEC without you.

GUADEC registration is open

Leave a reply

Online GUADEC 2014 registration is now open at https://www.guadec.org/register/

There is a limited number of rooms available which can be booked on registering and lunch vouchers can also be purchased.

The venue has changed to a more central location with better access to the city centre. It now looks like:

“Strasbourg hotHohenlohe a” by Ralph Hammann – Own work. Licensed under <a title="Creative Commons Attribution-Share Alike 3.0
” href=”http://creativecommons.org/licenses/by-sa/3.0″>CC BY-SA 3.0 via Wikimedia Commons.

Cincinnati, home of goetta breakfast sausage

Leave a reply

Dave, Petr, Mike, Jim, Shaun and I are now half way through Open Help in Cincinnati, OH, USA. This is the fourth Open Help and I’m happy to say that the documentation team has made it to all four so far (and also to Writing Open Source, the predecessor to Open Help).

We have heard a number of fascinating presentations so far, generally themed around engaging contributors and creating a community. Eric Shepherd talked to us about breaking down barriers to contribution and fostering the Mozilla community. Rich Bowen shared his wisdom on helping newcomers with documentation. Shaun McCance has been building a community around Clifton Market in real life, which has proven to be an interesting challenge.

Dave and I took the opportunity to talk about how the documentation team does outreach, the challenges faced with interships and barriers to contributions.

Tomorrow, the documentation team are going to start on the sprints where we will be working on the system administrator guide.

Running a documentation training session

Leave a reply

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.

Documentation team at GNOME.Asia

2 Replies

The documentation team will be at GNOME.Asia this weekend and we are running a session for newcomers today, and there’s also an introduction to GNOME 3 development session which is being run by David King. The GNOME.Asia team have been really great at helping us arrange and set up the training sessions, so they definitely deserve a big thank you!

There will be a re-run of the documentation talk during the conference, on Saturday, for those who are not able to make the pre-conference event and I will be happy to help give people a hand with making their first contribution to documentation!

I’ve also put together a pretty LaTeX beamer GNOME.Asia theme, which is free to use (and will be available as soon as I can upload it!).

Developer documentation

Leave a reply

The 2014 Developer Experience hackfest has just started at the Endocode office in Berlin. It was great of Chris to offer the space to us!.

GTK+ datamodels, API docs and hand written docs will be discussed today. The hand written docs will cover the developer documentation which comes from gnome-devel-docs and Ryan‘s HowDoI series on the wiki.

This evening, we are going to join the Berlin Open Source Meetup at the Prater. If you want to talk to us, come and join us!

Tomorrow we will move onto the GTK roadmap, including the new HIG, development tools and developer.gnome.org.

Documentation in GNOME 3.12

1 Reply

The documentation team have worked long and hard to make 3.12 one of the best documented releases in recent history. Thanks to our translation teams, it is also one of the best translated in many years.

The team especially appreciated the detailed bug reports about changes to the UI and functionality in some applications (thank you Debarshi and Christian, please keep them coming), and lots of proof reading by translators.

There has now been one full release since the translation/documentation BoF at GUADEC 2013 where we discussed implementing documentation freezes toward the end of the release cycle. As with many things, changes to UIs and functionality tend to happen closer to the deadlines rather than early on. With many changes happening in the Shell and applications over the last few years, this has lead to unstable documentation that has needed regular updates or rewrites. The instability creates a high workload on the team during the last few weeks leading up to the release. To complicate the issue more, both documentation and translation work often starts at the same time: after the UI freeze. Unfortunately, it also means that it is not practical for the documentation strings to be frozen as we do not have the resources to finish updates early. At the BoF, we came up with a work around: whenever the help was finished for a module, the documentation team would email the translation teams to let them know. We have now done this for one full release and the feedback has been very positive. Alternatively, the help statuses can be tracked on a wiki page, but the update notification emails are not pretty.

Another status tracking issue that we came across this cycle is that there is no easy way to view images and screenshots across all modules. I have gotten in touch with the damned-lies maintainers who have volunteered to see if they can adapt some of the webapp to work for the documentation team.

For the 3.14 release, the documentation team will focus on the system administration guide, alongside the usual user and developer documentation updates. Developer documentation will be reviewed at the upcoming Developer Experience hackfest and we are hoping to have a team meetup at Open Help!

The restart of the GDP Guide

Leave a reply

As the Documentation Team have been preparing the applicants for the OPW, I have been adding to the docs related FAQs. The original aim of those guide pages was to provide the team with coherent reminders of how to do rarely done tasks, such as adding new pages or updating screenshots.

After the docs/translation BoF at the last GUADEC, it expanded to include how to help our wonderful translation teams with their workflow. The guide now covers a small range of HowDoI tasks that the team does on a release-by-release basis which are out of the ordinary. It is also a good starting point for some common and uncommon issues that internship applicants come across.

Update to the GNOME travel sponsorship policy

Leave a reply

The Travel Committee have traditionally had a policy that local travel was not reimbursed unless explicitly agreed beforehand. The policy was not explicitly mentioned anywhere, so I have updated the wiki to make it more clear: https://wiki.gnome.org/Travel#Travel.2BAC8-Policy.Travel_policy

This applies to large events which are handled by the Travel Committee and to small events which are handled by the Foundation board.

Merging long-neglected user help

Leave a reply

When I first started contributing to GNOME documentation, it was not unusual for members of the Documentation Team to not have accounts for git.gnome.org. Instead, the team often worked on other infrastructure such as Gitorious. While in theory this is a good idea as it means that new contributors don’t need to have access to GNOME infrastructure, in practice, there are a number of drawbacks. The worst of these is when work on the user help stalls and is then forgotten about. This happened to a number of projects such as rhythmbox and gnome-system-monitor and in some cases, newcomers to the team started work from scratch when it was almost complete elsewhere, of which even I was guilty on one occasion when I first started contributing. At our last winter hackfest, we got our backsides into gear and finally moved all of the pending work that we could find to branches on git.gnome.org.

One of the tasks that we took on last year was to merge the gnome-system-monitor help to master. Unfortunately, there was a licensing issue. By “licensing issue”, I mean that there was no license for the work that had been done. The first thing we try to do in these cases is to contact all original contributors and ask them to add the license. This (eventually) works in about 80% of the cases, although it can take a few months for everyone to agree to the changes.

If we have lost touch with one or more of the original contributors, then it becomes a bit more complicated. In those cases, the only option left is to delete all the work that has been done by them and rewrite those parts from scratch. This is what we had to do in the case of gnome-system-monitor. Phil and Mike did a good job of fixing up the bits that needed while I reviewed some of the pages.

At this point, the user help has been in some form of existence where the content was almost good enough for merging for over 3 years. With the licensing issue resolved, the help was finally merged to master in the last couple of days. Within half a day, it was already half translated into Spanish by the awe-inspiring Daniel Mustieles. There are still a few improvements that could be made, such as restructuring the index to fit with the style of the other help and trying to shorten some of the page titles.

I was building gnome-system-monitor after every one of my commits and rebases while preparing it for merging. Once the help was merged, someone else who was trying to build it came across an issue that was likely caused by the removal of the old DocBook help and addition of the new Mallard help, where the Makefile was not regenerated properly. This problem was easily fixed by running git clean -dfx, which force-removes untracked files and directories while not using ignore rules from .gitignore.