Tag Archives: help

GNOME Docs in Cambridge: day two

Day two of the hackfest saw more progress…

Application and desktop help

I worked on merging new games documentation which was written by Rashi Aswani and fixing some of our 100-odd bugs against application help which Petr Kovar has continued triaging.

Jim Campbell started refactoring Files (nautilus) desktop help as the style of the pages was a bit outdated. It now looks awesome.

In the mean time, Jana Švárová continued powering through the feedback.

Licensing

gedit documentation saw some licensing improvements thanks to Jim. A number of the help pages had previously been published without a license which is something that the team has been fixing over the last few years. Adding the license after the pages have been written is a bit of an arduous task. Progress has been slow but steady.

Developer Documentation

Bastian Ilsø and David King made further progress on gnome-devel-docs. Bastian made improvements to the first user experience of writing an application using the platform demos and learnt the importance of validating the XML.

yelp

Around August 2014, the documentation team started accepting emailed feedback about the documentation from help.gnome.org. It has been quite a success and yelp will see this feature as soon as Shaun McCance can build it.

Mallard

Shaun also improved projectmallard.org, the home of Mallard, and furthered the development of DuckType, a markdown Mallard language.

The end

We finished the day with lovely cream tea, which caused a number of altercations due to cultural and regional conflicts.

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.

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.

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.

Updating documentation for 3.10

Leave a reply

With only a few hours to go until the 3.10.2 tarballs are due, here’s a recap of what the documentation team has been up to:

gnome-user-docs started being updated for 3.10 mid-September: it is moderately difficult to test the UI and functionality before the 3.x.92 release
the updates were done by 10 documentation team members and translators
after the docs-i18n brainstorming at GUADEC, the docs team made sure to keep translators up-to-date on what was happening
the changes in the UI affect almost every one of the 293 live pages
updating 293 pages takes a lot of time and the updates were not finished in time for 3.10.2 so there will be a 3.10.3 release sometime before next year
the translators appreciate the docs team how-to for taking screenshots almost as much as knowing what’s going on
screenshots are still a pain to update
the docs team sucks at giving translators enough time for translations

As the docs team has been concentrating on the desktop help, some of the application help has been neglected a bit, which is somewhat unfortunate. There are also a few things that could make updating both application and desktop help easier for the team, such as fewer UI changes between each major release, notification emails about freeze breaks (not all developers send these), fewer UI and functionality changes after the freeze.

Open Help, part 2

Leave a reply

For those of you who have not been before, Open Help has quite a standard conference layout of two conference days over the weekend followed by three hacking days during the week. As I mentioned before, I joined the travel committee a few months ago and was working on processing GUADEC sponsorsip requests. A number of the summer interns asked me to explain to them what is the difference between conference days and BoFs. So, this is what our conference days at Open Help were like:

And this was what our hacking days were like:

We took one look at https://developer.gnome.org/ and decided that it needed some care. After quite a lot of brainstorming and debate, we concluded that the structure of the Developer Center needs to be simplified, which is now a work-in-progress in master.

One of the biggest issues that we addressed is that the Documentation Team does not have the manpower to keep up with all the cool new stuff that developers should know about. Ryan is leading the effort to try a different approach which we hope may be more developer friendly when it comes to maintenance and new content with a “How Do I…?” series on the wiki.

In the mean time, we are aiming to merge the platform-demos, the examples and mini-showcase applications, into what is currently the platform overview.

For more details on the state of https://developer.gnome.org/, have a look at the Documentation Team’s planning pages on the wiki.

Open Help, part 1

1 Reply

Open Help is on this weekend in Cincinnati. We’re half way through the two conference days and have seen very interesting presentations from Jorge Castro about helping users help users, Janet Swisher on sprints and Rich Bowen about writing better help, which led to interesting discussions during the panel and open floor.

The trip over to the US was a bit long as Dave and I were delayed at almost every point of the way, but we finally arrived in Cincinnati after a 22 hour trip to a lovely reception at Via Vite on Fountain Square.

The conference itself has a very relaxed atmosphere. With around 40 attendees, it is possible to meet everyone and it is rather nice to have a fluid schedule. There are people here from a range of different projects, including Drupal, the Wikimedia Foundation and WordPress, including four people who previously participated in the OPW. Unfortunately, Sindhu and Aruna, the Documentation Team interns from round 5 and 6, could not make it because they have exams right now, but I am hoping to meet them at GUADEC.

Documentation sprint in Brno

Leave a reply

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

2 Replies

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

4 Replies

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 🙂