Phil Bull (philbull) wrote,
Phil Bull

GNOME Docs hackfest in Brno

A couple of weeks ago, I attended the GNOME doc sprint in Brno, which ran in parallel with the Red Hat Developer Conference. My flight came into Vienna, where I was met by Shaun McCance and Florian Nadge. After a rather bizarre lunch at a Greek restaurant (Free wine! Free dessert! Expensive meal!), Shaun and I took the train to Brno, narrowly avoiding a trip to Hungary in the process. The Czech Republic is seven shades of awesome. The countryside that we passed through on the train was beautiful (even more beautiful on the way back, when the snow had melted and the Sun was out), and Brno seems like a pretty cool place to be. Food and drink are super, super cheap, at least when you're used to Oxford/London prices, and pretty much all the meals I had were excellent. Maybe we were only eating in nice places? I don't know. I only wish the concept of vegetarianism had made its way over there in a bigger way - I'm on a bit of a pescatarian kick at the moment, so I could eat fish at most places, but vegetarian options were few and far between. (Amusingly, one restaurant managed to stuff a fish with parma ham, while omitting to mention this fact on the menu. Ho hum.)

We spent a few days at the Masaryk University while the developer conference was on, and had a couple of decent topic brainstorming sessions. It was really good to see so many familiar faces - the Docs team has been growing at a steady pace over the past couple of years, and we now have a good number of people interested in both developer and user docs. We found some of the new changes for GNOME 3.4 quite challenging to write about - a lot of the new UI's were incomplete and buggy while we were working on them. It was useful to be able to bug the devs in person, though. That's why hackfests are so great - you can drag the maintainer of some app into the docs room and review the UI with them, pointing out what users will struggle with, while finding out directly what will have changed by release time. Repeatedly reviewing UI changes is a gigantic pain for docs people, since we have so many topics to review - one string change, and a whole bunch of help topics can be rendered useless. It's useful to be given a thorough "heads up" about stuff like that, and that's what we got.

GNOME Platform Overview (1)
The hackfest went extremely smoothly this time around, partially because we didn't have to fight with the facilities at all (the wireless held out!), and partially because Jim is a genius, and got everyone to arrive with a recent, working version of GNOME 3.x. Jim wins. We spent the first few days either brainstorming topics, or reviewing the desktop help for correctness. We have almost 300 topics in that document, so it's a big job. That was a good warm-up exercise for everyone, I think. We then moved on from the university to Red Hat's Brno offices, where people started to work on separate projects. I spent some time restructuring the platform overview, which has been a thorn in our side for quite some time.

The idea was to make it so that new developers could find their way around the platform, understanding what capabilities are available, where they can be found, and how to use them. One particular hurdle to new developers is getting a toolchain set up to do even basic things, so I added some "conceptual overview" topics, and "getting started" guides. It's also important to make people realise that GNOME isn't really like any other platform - there's no SDK, no one, blessed, distribution channel, no one company responsible for technical support. We need to prepare people to handle this, so that they don't get confused and put off from using the platform. I then broadly categorised the various libraries in the platform by function, and wrote "marketing" overviews for some of them. Each overview explains some of the cool things you can do with the libraries, has links to different types of resource for the individual libraries, including conceptual material, guides/manuals and, importantly, example code, and also points at existing GNOME apps that use those technologies.

I think that building a library of example code snippets is a very valuable exercise - you can learn a lot from seeing one, simple feature implemented in a few lines of code, completely separate from any boilerplate or other stuff. It's important to allow people to get something working quickly, by gluing together little chunks of code here and there. Otherwise they lose interest. Once they have something that just about works, they can then go on to refine it, and "do it properly". That's how a lot of developers learn, I'll wager. Pointing at existing apps that make use of the various parts of the platform is also important. We should milk our open-source credentials more when we talk to developers - people have solved all sorts of problems using GNOME technologies, and so we should make it easier for outside developers to inspect the relevant bits of code so they can see the solution without having to figure it out for themselves. Tiffany and Susanna did a lot of work on the developer tutorials too, which are very useful for brand new developers. Those will be merged into the platform overview too, alongside the shorter example snippets. Much of the overview is in stub form at the moment, but we plan to develop it over the next release cycle or so.

GNOME Platform Overview (2)
People were working on a lot of other stuff besides, but this is already a long blog post, so I'll leave it up to them to explain what they did on their own blogs. Everyone worked really hard, and it was an absolute pleasure to spend the week with a group of such fun, dedicated folks. It was even good to see Ryan Lortie. So, well done Shaun, Jim, Tiffany, Mike, Andre, Kat, Dave, Baptiste, Tomeu, Julita, and Susanna, you rock!

And that's not to mention our hosts. I need to say a massive thank you to Florian, and Petr, for being so great. They helped us with travel arrangements, showed us around town, gave us somewhere to work, translated for us, ordered food in for us... The whole nine yards. It was amazing. The language issue was especially difficult for me - I can get by in most places where they speak either Germanic or Romance languages (at least some of the words look familiar), but I was completely lost with Czech (which is Slavic). I think we would have had a pretty confusing time without them. Andre Klapper was also magnificent, putting up many of the docs people at his apartment before their early flights the next day. So thanks, guys, you are awesome! And thanks to Red Hat, and especially to the GNOME Foundation, for sponsoring the whole thing, and making it possible to bring all of us together to work on GNOME.

Sponsored by the GNOME Foundation
Tags: brno, developers, documentation, gnome, hackfest

  • Open Help 2011 - Cincinnati

    We live in strange times. I woke up on Saturday morning to find that I'd been magically transported to Cincinnati by a benevolent spirit. And…

  • GNOME 3; User Help hackfest

    GNOME 3.0 released Well done everyone! User Help 2011 hackfest Well, the User Help hackfest in Toronto went swimmingly! Blip tells the story.…

  • GNOME Women: Work on docs!

    It's time for another round of the GNOME Outreach Programme for Women! I recently got back from spending a week in Toronto at the GNOME docs…

  • Post a new comment


    default userpic
    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.