How to host a hackathon

Thursday, September 5, 2019



Are you interested in the work that goes into hackathons, or perhaps just curious to see the work that goes into Humanitarian Toolbox? This blog post is the beginning in a weekly series of topics relevant to Humanitarian Toolbox and the work that goes into it. Each week our team will be supplying a new entry on the different conflicts and challenges that come from our tech charity, and will give you a better look of how our events come together. 

Our first topic on hackathons aims to collect and share all that our team has learned so far from planning and executing a successful coding event. Every event we take what we’ve learned and use it to improve our scheduling and planning, with success. Each new event sees improvements in areas like building more software, constructing more features, and gaining more satisfaction from our volunteers.  Ultimately, we aim to improve as we learn more from each later event.

Early Planning

While we can move fast, ideally, we should start planning for an event 3 months prior to the dates. We can provide more leeway in those cases where the event is for a private company, and we will have more support and we will need to do less of the demand generation for volunteers.

All of these actions should be completed by 30 days before the event:

  1. Estimate the attendance for the event. As the size of the event grows, we will need more features or applications for volunteers to work on. We want to maximize the amount of work that gets done, and that means minimizing the integration issues between feature or application teams.
  2. Pick the app / project that will be the focus of the event. Depending on the expected attendance, we may work with more than one application. When we have multiple applications, we may want to consider a ‘primary’ and a ‘secondary’ focus. That depends on the size of the estimated attendees, and whether a member of the requesting organization can and will attend.
  3. Secure the venue. This may be a checkbox item for those events that are hosted by a corporate partner, or are co-located with a conference.
  4. Secure food and other logistics. Other logistics include internet access, building security protocols, lodging, travel.
  5. Recruit volunteers. It’s important to remember that we need volunteers outside of developers. Our most successful events have had help with the logistics, scrum master, UX design, and most importantly, domain experts from the requesting organizations.
  6. Build (or update) the project backlog. This will be done with the HTBox coordinators to manage expectations around customer rollout. There are several sub-tasks associated with this task to ensure that our developers are as productive as possible:
    1. Review the existing issues and update the priorities.
    2. Label existing issues. Pay special attention to the “Jump In” tag. Also, update based on “bug” or “feature” tags.
    3. Add any new requirements in cooperation with the requesting organization.
    4. Define a milestone for the event.
    5. Assign issues to that milestone. These can also be subdivided for P1, P2, and P3 goals. A successful event should be able to manage all the P1 issues even if the attendance drops. Stretch goals could be P2 and P3 issues for the milestone.
  7. Define initial milestones. By 30 days before the event, our most engaged volunteers should be able to begin working on some of the features. This task also has a number of sub-tasks:
  8. Clean up stale milestones. Often earlier events may have left some unfinished tasks in the existing milestones. These can confuse volunteers: Some volunteers assume they should work on these issues; others assume those issues should be dropped.
  9. Define milestones for before and during the hackathon event. We should define weekly scrum milestones leading up to the event.  These should include tasks for onboarding volunteers (fork the repository, clone and build the code), and simple tasks to help developers become familiar with the project (scoped bug fixes).
  10. Assign issues to the milestones. This is the first pass assignment and will likely be refined each scrum. Historically, we have had higher velocity during the event than before. However, there may be advantages to defining slightly aggressive milestones leading up to the event in order to encourage work.

March to Event

Starting one month before the live event, we want to start building momentum. The purpose of building this momentum is to make the in-person event a “sprint to the finish” rather than a launch event.

  1. Assist with onboarding volunteers. This has generally meant teaching .NET developers about Git, GitHub, Github Desktop, and the Fork / Pull Request model. We have also had to help developers learn how to pull upstream changes into their local fork. Pro tip: Just explain the fork / pull model. Experience has said no on asks until they’ve made days of work on a local cloned copy only to find that they do not have commit privileges.
  2. Stress the automated unit tests. It has really helped volunteers have confidence. They can make changes and run the existing unit tests to feel confident that they haven’t introduced regression bugs. I’d like to start from a position that we won’t merge a PR without new tests, but that may not be practical. The carrot is that we will help them create the tests.
  3. Encourage feature teams to open their pull request early. We can comment on the code as they are working. It can help us ensure that we can avoid work going in the wrong direction. Tag that PR with the ‘WIP’ tag. (It stands for ‘Work in Progress’). That tells reviewers to comment, but not merge the PR.
  4. Schedule online standups / scrum meetings. We should touch base with the volunteers each week during this period. We can answer questions, encourage more involvement, and create a sense of community. HT Box project leads will also attend these meetings. Have also experimented with recording the weekly meetings each week.
  5. Refine milestones after each mini-sprint. During each online meeting (or offline afterward), the HTBox principals should update the board for the next sprint. This may include reprioritization (with the requesting organization), and pulling issues into or out of milestone sprints. 
  6. Setup a schedule to review and merge pull requests. Volunteers are giving us their time, and the sooner we respond to their pull requests, the ‘stickier’ those volunteers become. We do all have busy schedules, but we need to ensure that we can respond to a pull request within 24 hours or so. (Note that for really large PRs the review may take longer. When that happens, the reviewer should add a comment that they’ve started the review.)
  7. Setup slack channel. We’ve all used Slack with different organizations. We’ve all had positive experiences. We’ve found this is a good way to get volunteers communicating with each other.

Finally, right before the event, we need to define the final milestone and update the backlog with the issues we want to complete during the event.

At the Event

The event is the key momentum builder. We want all the participants to have a great time, and feel that their time was well spent. Here are the keys we’ve found so far:

  1. Welcome and ice breaker. Get people talking as soon a possible when they arrive. We’ve never done a formal ice breaker activity, and we believe the developers would not respond well, but we need to do what we can to get teams to gel quickly.
  2. Get permission to use pictures and names from volunteers. (See next section).
  3. Introduce the ‘customer’. This has had two very good effects. First, developers know who can answer feature questions. Second, and more importantly, it puts a face on the problem and the work. It’s been energizing for the volunteers. When the customer is not there in person, schedule a skype call at the event start.
  4. Take some B roll shots that can be used later in PR activities. Where applicable, get a short interview from the customer and some volunteers.
  5. Continuously manage pull requests. The HTBox core team will be spending their time reviewing and merging pull requests. This activity will grow as time goes on. By the end of the event, we’ll be spending all our time merging and updating the core repository. As the pull requests start coming more quickly, we will need to make sure people re-base their pull requests so that merges are easier. (You did explain rebase when you introduced git, right?)
  6. Recognize team members. We need to be the cheerleaders during the event. I suppose we could go too far with recognizing volunteers, but we haven’t seen any evidence of this yet.
  7. Remember to mark issues as closed (If the PR doesn’t properly identify the issue or work item.) Communicate progress toward the milestone.
  8. Consider recruiting a project leader. We can’t scale if we are the only possible project leads. One of the HTBox principals should be always involved, but when we can identify potential leaders, we can scale.

Post Event

After the event we want to capitalize on the event. We want to capitalize in two ways. First, we want to keep the volunteers engaged after the event. Second, we need to publicize what happened and grow awareness of what we did.

  1. Review the issues list. The end of the event is the end of another sprint. We need to groom the board just like we do for other sprints.
  2. Define new milestones. We want the existing volunteers to stay engaged. We need to define the next milestones.
  3. Assign issues and tasks to milestones. This will give the volunteers guidance on what to work on as they stay engaged.
  4. Write Blog post. This is the first public announcement. We need to publicize our success. Make sure to highlight many of the volunteers. (See previous section for permission). Add the photos or videos from the B roll. It needs to go live within 3 days of the event.
  5. Press Outreach. After the blog post has been written, we should create the short press release and announce what we’ve done, in the markets where the event occurred, and the home market for the app’s test deployment. This can refer to the blog post for more details.
  6. Encourage continued involvement. Immediately after the board is filled, we can continue to engage volunteers online and encourage more involvement. If we have identified a potential project lead, we can help engage that person to transition the day to day project leadership.
  7. Work with requesting organization to encourage a (test) deployment. Assuming we’ve met our goal, we should push for a deployment that can create a second press story, and a chance to reach out to those volunteers that have helped to show how their work has been used.



While this is the sum of our knowledge from the hackathons that we have hosted so far, we strive with each hackathon to improve upon our guide.  We’ll revisit this document after each in-person event in order to share and expand on our body of knowledge and to use as a resource for the future. 

-Bill Wagner

Humanitarian Toolbox President