Documentation sprint in Brno

The documentation team is back in Brno for another week of writing this year. We are working on updating help pages in time for the GNOME 3.8 release: I am working towards merging gnome-system-monitor and Sindhu‘s rewrite of the gnome-terminal help. We are also working on new help for gnome-boxes, although it will still take some time for us to finish as most of the pages are stubs.

In the mean time, Dave and Marta have been working on developer documentation, updating the Python tutorials and fixing bugs.

As last year, we spent the first two days of the hackfest at Masaryk University and we are at the lovely Red Hat offices from today.

The only downside to this hackfest has been that Sindhu’s visa application was refused, so she could not attend in person, but she is joining us using Google hangouts!

GNOME documentation hackfest in Brno

The documentation team had a very productive, week long hackfest in Brno that finished last week. We could not have had it without the nice workspaces that were provided by Masaryk University and Red Hat, while Florian Nadge and Petr Kovar did a great job looking after us, even making sure that we got fed tasty pizza on demand so that we could keep going. Syllogist (and Shaun) also treated us to a lovely dinner.

At the hackfest, the team managed to update large chunks of gnome-user-docs for GNOME 3.4, while Susanna and Tiffany added tutorials to developer documentation, and Dave fixed lots of glib and GTK+ API documentation. We were also treated to interesting demonstrations of Boxes and Documents, and we planned out user help for Online Accounts.

Julita has been working on porting the baobab user help from DocBook to Mallard. The first (basic) pass is now complete, but there is still some more work to be done. baobab is also currently being re-written in Vala, so any help from Vala enthusiasts would be very appreciated!

Updating Vinagre help

A couple of months after I finished rewriting the Vinagre help in Mallard, I have had to come back to it because the user interface changed quite significantly (and will continue to change), so some of the help pages needed rewriting/removing/reordering. Dave also noticed that the online version of the help was rather old and Damned Lies showed more translations of the help than actually existed.

One bug and a fix later, the online version should always be up-to-date now. Damned Lies has also been updated (the bug was fixed very quickly by Claude Paroz) which was followed by a surge of translations! More are always welcome 🙂

Help and help again

I based my application for the Outreach Program on a DocBook to Mallard port of the Vinagre help.. suffice to say, it wasn’t that great. So, I have now fixed it up, with some pointers from Shaun, to be more topic-oriented and less *ahem* technical.

I have since started working on Brasero. This time, I have an advantage of starting with some notes for what should be included in the help, which were written up at the Open Help Conference brainstorming sprint. While writing instructions on how to use the application is not particularly challenging, I am finding that writing in a way which is “not technical” and understandable by users who would look at the help quite difficult, because terms which I take for granted are often misunderstood or not known by the audience I should be aiming at.. which is probably not anyone reading this blog. But the biggest problem I have come across is that Brasero could do with some love and care. I won’t count the number of ways of making it crash that I have managed to find, but with 229 open bugs, it is in need of some maintenance.

I have not been able to find a good guide on the style of the writing needed for user help, so I have been using the Empathy help as an example, with Shaun giving me feedback as I go along.