Blog by Sumana Harihareswara, Changeset founder

01 Sep 2011, 18:22 p.m.

Everybody's Doing It: Some Hackathon Tips

Hi, reader. I wrote this in 2011 and it's now more than five years old. So it may be very out of date; the world, and I, have changed a lot since I wrote it! I'm keeping this up for historical archive purposes, but the me of today may 100% disagree with what I said then. I rarely edit posts after publishing them, but if I do, I usually leave a note in italics to mark the edit and the reason. If this post is particularly offensive or breaches someone's privacy, please contact me.

Hackathon 2011 Berlin - 2ter Tag - TS (44)I'm helping arrange some developers' events at work. They're meant for open source software developers, testers, documenters, and other contributors to get together, talk, and collaborate. We often call them hackathons. I'm directly planning, with a colleague, the October 14-16 hackathon in New Orleans. But I'm also advising volunteers and people at partner organizations who want to put on technical events -- for example, a British contributor is planning a hackathon in Brighton, 19-20 November. The Wikimedia Foundation itself can only put on a few events a year, but there's plenty of room and demand for smaller regional meetups, so I'm enthusiastically encouraging volunteers who want to throw a hacking party.

People keep acting as though I'll have useful advice for them in hackathon planning, so here goes! I do not want to reinvent the wheel here, so I'm liberally linking to others' existing guides and HOWTOs.


Wikimedia Hackathon Berlin 2011 group photoMy colleague Siebrand Mazeland wrote some goals for an upcoming hackathon and I like them as an example. Note that this is for an event where we're expecting that most participants will be new to MediaWiki and to open source development in general:

  • Inform participants about how the MediaWiki community works
  • Inform participants of the major development languages and tools for MediaWiki
  • Provide a brief, comprehensive, accessible overview of the exciting projects MediaWiki developers are working on -- convey that anyone with PHP knowledge, and who wants to build an excellent open source CV, can participate in the community
  • Get current developers talking to prospective developers
  • Get a few people (1-3) that were not MediaWiki developers beforehand to be MediaWiki developers within 2 months after the hackathon

First I'll talk about the social/content side of hackathons, and then some outreach/process stuff, and then the technical/logistics side.

People & Activities

Here's what I wrote while helping plan an upcoming hackathon, one of the first in its region:

Hackathon P1030931

Since I predict that at least half of the participants will be new to MediaWiki-related development, we'll want to seed the crowd with some more experienced developers (if possible, from the region). And we'll want to provide some direction and some pre-planned activities, especially for the first day (if we're assuming a two-day hackathon).

One of these activities should be the "how to start modding MediaWiki" lecture/workshop that we first led at Wikimania. A colleague and I will be cleaning up those notes in September to create a curriculum that a local developer could use to teach.

Other preplanned activities would include just enough structure to help inform and guide the energy of new, uncertain participants. For example, organizers should ask several local developers, ahead of time, to prepare sets of tasks that small groups could work on, such as "fix these ten bugs in Kiwix" or "add language support for (this language) to (tool)." It would be best if these developers could also give extremely short talks about their areas of interest (3-5 minutes each, no slides necessary). In the afternoon of the first day, and at the beginning of the second day, there would be a twenty-minute period of these "lightning talks" and then participants could decide what group to join.

Hackathon 2011 Berlin - 2ter Tag - TS (65) I am generally in favor of allowing some room for spontaneity, by asking participants on the first day what they're interested in working on, encouraging them to give ad hoc lightning talks during the short talks sessions, and by encouraging participants to lead sprints on topics of their interest. Technologists feel more inspired and creative if there's lots of support (people who are willing to teach and mentor) but also freedom to discover and concentrate on new interests.

It's tempting for organizers to say "let's concentrate on this! and this! and this!" at a hackathon. But you can't concentrate on localisation, and mobile, and accessibility, and HTTPS, and mass uploaders, and usability, and the article feedback tool, and and and. :-) If you really want some topic focus at the hackathon, choose maybe 2 concentrations a day, and target your outreach and publicity, saying that you especially welcome participation in those areas.

Some Things You'll Need for a successful developer outreach event:

  • a public wiki page stating the date, time, and venue, and specifying that everyone is welcome. Also tell people what to bring (laptop and power cord), ask them for topic ideas, and ask them to put their names down -- no obligation. A sample.
  • outreach/publicity drive, starting at least six weeks in advance, to relevant communities. Ideally you'd get the word out to technical interest groups, local user groups, consultants and other businesses in the industry, individuals whom you want to attend, professors and colleges and universities and technical schools and trainers, email lists, and (if relevant to your audience) newspapers.
  • some experienced developers. I don't know the exact ratio, but perhaps a fifth of your participants should be people who have had some experience in developing Wikimedia/MediaWiki stuff, loosely defined. You need some seeds.
  • documentation tools & some people who will take notes with them (more below).
  • lightweight tracking. At some point, somehow, at the event, get every participant's name and email address. That way you can follow up and continue encouraging them after the event.

Technical stuff & logistics

Hackathon 2011 Berlin - 2ter Tag - TS (75) I find that the Stumptown Syndicate's Event Planning Handbook section on logistics ably summarizes the logistical side of what's needed at a technical event.

Basically, once you have a venue, the next priority is provision for robust wireless (and, if possible, wired) internet, and provision for heavy electrical power usage.

You'll want to have some kind of documentation of your hackathon, to make it easier for people to collaborate (face-to-face and remotely), and to have a record for future reference. As we decided for the Berlin WMDE hackathon this year (thanks to Daniel Kinzler for distilling this hierarchy):

  1. textual documentation: essential
  2. live textual documentation (IRC, Etherpad): important
  3. photo documentation: important
  4. audio recording: important
  5. video recording: would be good
  6. audio streaming: would be good
  7. video streaming: nice to have

It's great to have two dedicated notetakers/facilitators typing into Etherpad for collborative notetaking, finding and answering questions on IRC and blogging, and walking around talking to people and asking them what they're working on and helping them collaborate more effectively.

Hackathon P1030929 And below I'll reproduce a note that Jon Davis, formerly of Wikimedia internal IT, wrote about audio recording and streaming (when planning for the Berlin WMDE developers' days):

The biggest problem is getting reasonably quality audio to a computer. The single biggest complaint I've had... was that it was hard to hear people. [You'll] need some reasonably quality microphones to capture with. If it is presentations, I recommend some sort of shotgun style mic. If it is a group talk, something omnidirectional. The trouble is twofold.

#1 - I couldn't find any USB compatible shotgun mics off hand. You can, in effect make one with the right parts [1], [2], but it's definitely not cheap.

#2 - The USB omni-directional that I found [3] isn't cheap, and I've no idea what the quality is.

So [you'd] need at least one mic setup (and probably computer) per area [you] are trying to record. It's not... "great", but it sure beats running a ton of cable, doing mixing and all sorts of much more pro level work. I have no idea what the budget is for that sort of thing, so it might not be a big deal...

There is probably far better advice out there regarding recording/streaming video and audio. I welcome links and experiences.

You'll also want to consider bathrooms, garbage needs, whiteboards and markers, and maybe childcare, and so on -- the sorts of things conference organizers need to consider, in general. A few guides with tips on what to consider:

And of course there is a lot of "how to run a conference" reference material available for your perusal, including ConRunner, which focuses on science fiction convention organizers but which has more generally applicable advice. And hey, they're running MediaWiki!

Questions, links, comments welcome in the comments.


02 Sep 2011, 7:04 a.m.

Jesse Scott's description of how he did audio and video for the 2011 Wikimedia developers' meeting:

"For the betahaus event, I set up a Livestream account, downloaded the Livestream Studio app (which I believe is Flash-based, which sucks, but I've never had a lot of success with Open Source streaming packages to date), and used a firewire capable DV/HD camera for the streaming, along with an extra microphone.

"As long as you have Quicktime installed on your streaming computer (on any OS), Livestream should see the camera as an available choice.

"Obviously, a proper DV/HD video camera will have access to manual zoom, iris control, white balance, etc, which is great for adapting to different rooms. This way, you can also record to tape as well.

"I also made sure that I had a dedicated ethernet line, so that I my upload speeds would be sufficient (500kbps +) for continuous streaming.

"For audio recording, I got a stereo signal off of the mixing board, and also mixed in the camera and computer microphones (Livestream Studio has a mixing board within the software).

"If there was one thing I could have changed, it would have been to have a shotgun microphone and some extra audio cable, to better be able to focus in on the speakers. But that was a bit of a concern for our room, which was a large concrete box, so had lots of reverb."

Thanks, Jesse!

Jessie Wild
02 Sep 2011, 13:44 p.m.

This is awesome, Sumana!

Are you going to be recording this on one of the Wikis somewhere?? It would be great to make sure we have this captured :)

03 Sep 2011, 0:21 a.m.

I'll have to ask Jessie what she means by "this" -- the blog post, or a recording from a future hackathon?

Another goal to consider: number of participants! Could be "ten" or "forty" or "seventy" or some other number.

11 Sep 2011, 22:31 p.m.

I was sort of talking with Karl about hackathons (and how sexy they've become) yesterday and I feel like step zero has got to be: DECIDE WHETHER OR NOT THE EVENT SHOULD BE A HACKATHON. I feel like the panel he spoke at yesterday at OVC was so hampered by this hackathon/unconference focus on having "concrete outcomes" that it was sometimes hard to have a discussion. I think that education and consensus building is time-consuming work and having conversations about Big, Important Issues should not be shoved by the wayside in favor of mindless do-ing. You know me, I am a do-er, but there is a time and a place for doing and thinking and talking deserve their time and place too!

11 Sep 2011, 22:33 p.m.

I meant to say "but while there is a time and place for doing, thinking and talking deserve their time and place too!"

12 Sep 2011, 8:46 a.m.

Camille, I completely agree! And perhaps some people are kind of afraid of discussion, because they are not good at it and/or worry that most participants are not good at it, and because concrete outcomes are easier to justify.

Also, different kinds of presentations and discussions are appropriate to less technical audiences, or to audiences where everyone is already well-versed in the topic (alignment/relationship-strengthening rather than outreach). For events where we're more focused on facilitating collaboration in the existing MediaWiki/Wikimedia technical community, goals are more like:

* Get WMF developers talking with non-staff<br/>* Squash some number of bugs<br/>* Get consensus on certain feature designs and plans<br/>* Spread knowledge & align community<br/>* Provide a brief, comprehensive, accessible overview of the exciting cutting-edge projects that will affect developers in the future, and recruit help<br/>* Get stuck projects unstuck<br/>* Sprint on topic of focus, achieve messy version 1<br/>* Get a few MediaWiki technical contributors (2-4) to substantially increase their contributions within 2 months after the hackathon