MDN/Hack on MDN/How to guide

From MozillaWiki
Jump to: navigation, search

How to run a "Hack-on-MDN" event

This page provides guidance on planning and running a "Hack-on-MDN" event. See MDN/Hack on MDN for background on these events.


Determine the goals

Have a clear idea of what the goals are for the event, for both content and community. This helps drive your planning of lower-level details.

  • Do you want to document a particular topic area?
  • Do you want to create a particular type of data, documents, or resources? For example, code examples or translations in a particular language.
  • Do you want to attract new people to contribute to MDN?
  • Do you want to increase cohesion among existing community members?

Based on these factors, choose a duration and a format. This guide focuses primarily on in-person events, but it is possible to have a Hack-on-MDN event that includes remote participation or even one that is entirely virtual.

Pick dates and times

For in-person stand-alone events that require travel, we've found that three days (such as two weekend days plus one weekday) is enough time to get some significant work done, without taking too much time away from everyone's normal lives.

For events in conjunction with another, larger event such as a conference, a single day added on before or after the main conference works well. If the conference already has an "extra" day for tutorials or open-source "sprints", you may be able to piggyback on resources such as space that are already allocated. Work with the conference organizers as early as possible in this case, and ensure that your event is included in their promotions, so attendees know to include the extra day when booking travel and hotels.

Whether to add the extra day before or after the main event depends on factors such as space availability and timing (e.g., the day of the week). Scheduling before the main event means that attendees are still fresh and enthusiastic. Scheduling after the main event enables attendees to deepen relationships they may have just formed.

Note: Scheduling a Hack-on MDN-event during another conference or event has historically not worked well; attendees are typically more interested in the main event, and don't have blocks of time to concentrate on hacking.

Get in touch

Once you have decided the focus and date of the Hack-on-MDN event (or even before), be sure to tell the MDN staff team (contact Janet Swisher, We will try to make sure we have a team member either attending in person or standing by remotely to help with the event. (In particular, creating new pages is an elevated privilege, so there should be someone involved in the event who has this privilege if any new articles will be created.)

Promote the event

Even if your event is open to the "public", you should invite a few key people whom you know will participate. Work with them when selecting dates, to ensure that they are available during the chosen dates. If these folks are well-known experts in the topic, you can to use their involvement to help promote the event.

For public events, identify existing groups that have an interest in the topic. If the Hack on MDN event is connected to a conference, the conference attendees are an obvious pool to tap. You can also, for example, promote it to local web-developer meetup groups in the area where it will be held. Send an announcement through whatever channel is appropriate to that group, in addition to any other general promotion you do.

Use the social media channels that are appropriate to reach your target attendees. We have found that for Web developers, this means Twitter, more than Facebook or LinkedIn. However, popular channels can vary geographically (such as Orkut in Brazil). Reach out to a few well-connected people who have a large following among your target audience, and ask them to re-share your posts.

Here is a template you can use to describe a Hack-on-MDN event. Feel free to add more detail, and give it your own tone:

Come help improve {topic} on MDN Web Docs! In this full day hack-a-thon we'll be working to improve MDN Web Docs, the premier free resource for web developers. MDN Web Docs ( is a source of references, guides, and tutorials on standards-based web technologies, much loved by web developers. It was chosen as #1 for Documentation in the Developer’s Choice Awards for 2018, conducted by SlashData.
Yet, MDN Web Docs needs help from {topic} experts and enthusiasts—whether you are a programmer, designer, or someone else who cares about {topic}. You can choose to work on {activity1}, work on {activity2}, or anything that you think makes sense.
During this {duration} hackathon, you will become familiar with how to contribute to MDN, and have fun collaborating with other participants. Activities will include a lot of coding, chatting, food, and fun.

Budget and resources

You need to figure out how much the event is going to cost, and where the money is going to come from. If you have sponsorship, you may be able to expand your budget. However, it is possible to boot-strap an event by finding free or donated space, and asking participants to pay for their meals and other expenses.

To request sponsorship from Mozilla, submit a Developer Events Request Form, following the developer events request guidelines.

Costs to consider in your budget include:

  • Meeting space
  • Travel and lodging (for attendees you are sponsoring)
  • Food
  • Fun

Meeting space

If your event is connected to another larger event, space may already be taken care of. Or, you may need to pay for extra time in the same venue as the larger event. Otherwise, there are lots of options for meeting space. If you are in a city with a Mozilla office, you can request to use the community space in that office. Elsewhere, options include meeting rooms in libraries, churches, coffee shops, or businesses where you have contacts. Many cities now have coworking spaces that rent their conference rooms for a reasonable fee.

Be sure that your venue has good chairs and tables, and reliable power and Internet access. Sitting all day on a bad chair is not just uncomfortable; it can lead to injury. Make sure that the number of attendees and their computers and devices does not overwhelm the power supply and available Internet bandwidth. Be generous (but not dangerous) with extension cords, and if necessary, international plug adapters. A projector for shared viewing can be very helpful. Whiteboards and sticky notes are great for brainstorming and planning.

Travel and lodging

Typically, travel and lodging costs are self-funded by attendees of the event. However, if you have funding to be able to pay these costs for participants who might not otherwise be able to afford to attend, doing so can broaden the range of perspectives at the event. You can also enable more participation by partially reimbursing costs for attendees.


Attendees need to eat! Make arrangements for food during the event, and inform attendees whether meals are included. If your venue allows, have snacks (some healthy and some not) available between meals. If nothing else, make sure there is coffee!


Allow time for social activities. These can be informal, like going for a hike together, or more formal, like a tourist excursion. Going out for drinks is usually a winner; be sure that non-alcoholic options are available. On the other hand, don't plan every hour of every day. Everybody needs some down time, especially introverts.

Registration and fees

Have a way for participants to pre-register for the event, so that you can have an estimate of the number of people you will get. You can limit the number of registrations if your space is limited; or you can book a larger space if the response exceeds what you initially planned for. If the Hack-on-MDN is connected to a conference, work with the conference organizers to see if an option to sign up for Hack-on-MDN can be included in their registration process.

Keep in mind that you will need one co-leader for every 12-15 participants, and that 30-40 participants is about the maximum number that can be easily handled.

It is a good idea to charge a nominal fee, to discourage people from registering but then not attending. An amount that roughly equals the per-person food budget is reasonable.

If you are including remote participants in the event, have them register, too (with a no-fee option), so that you know who to expect and can contact them with information about how to participate remotely.

Make sure that your registration process sends a confirmation of the date and location, and includes reminders of what to bring or prepare. In particular, participants need:

  • Their own laptop (seems obvious, but a reminder never hurts)
  • A GitHub account, as GitHub is used for authentication on MDN

Planning the work

Ahead of the event, once you know the topical focus, you can collect tasks that can attendees can work on during the sprint. There may be generated lists that can be helpful, such as lists of pages with a particular tag or flag, or bug reports, etc. Or you might collect items that need to be worked on into a spreadsheet for tracking purposes.

During the event

If you have remote participants, be sure that they have all the same information as on-site participants, through online tools, conferencing, and chat apps. Include remote participants in the opening and closing phases of the event, via video conferencing, if possible.

At the start

Be sure to make an introduction at the start of the event. This need not be formal, but be sure to introduce leaders of the event, point out logistics like bathrooms and emergency exits, and mention the Code of Conduct for the event. (Mozilla-associated events are governed by Mozilla's Community Participation Guidelines; the shortlink is ). Have attendees briefly introduce themselves and state what they're interested in working on, so you can help them find others to collaborate with.

Tracking tasks

Have a way to track what tasks need to be worked on, who is doing what, and what has been completed. If you have remote participants, the task-tracking tool should be available online. A Google Doc or etherpad can be good for this purpose. If all the participants are present in person, then a whiteboard with sticky notes can also work well.

Often, people want to help but don't know where to start, and deciding among many options takes too much mental effort. For any given participant, give them a couple of possible tasks ("you could do A, or B"); this simplifies their choice, without making them feel like they're being bossed around.


One of the benefits of in-person events is that people can work together in ways that they might not be able to when they're not in the same place, for example, by working out ideas together on a whiteboard or by brainstorming with sticky notes.

As an organizer, look for common interests among the participants and for ways that they can work together. If everybody works solo the whole time, they could have equally well stayed at home.

Celebrating accomplishments

Be sure to take time to celebrate accomplishments at the end of the event. This gives participants a better feeling than when the event just ends without any summary. If possible, have people "demo" what they have done, even if it is just showing a new article page.

After the event

Share the event accomplishments via a blog post, to celebrate publicly in addition to the demo at the end of the event.

Finally, also thank participants individually, via email, with a personal note about what they contributed. This both helps them feel appreciated, and encourages them to continue with what they started during the event.