Documentation is usually written by people who are subject matter experts, people who have lost the beginner lens. For beginners, this is a tough situation. When one first enters the fray of, say, an MVC framework, there’s a lot of big picture concepts that need to be covered before getting into the granular details. I had decided, at some point, to build a Django app for my Burning Man camp, and spent a good two months wading through tutorials and official documentation before deciding that it was time to stop swearing at home by myself and throw a nerd party sprint.
I wanted to create a space where people would not only learn Django, but also make their first contribution to an open source project. Did you know that women make up only 3% of contributors? And that the mean number of open source contributors is one? This was an opportunity to be constructive, and create a welcoming space for new engineers who would hopefully be inspired to contribute to open source frameworks. Hackbright offered to host, and I connected with Angie, their Director of Growth, Nick, instructor at large. We recruited a couple of other people we knew had both technical knowledge and an interest in community building – Jeremy Dunck is a Django expert and a mentor to many coders, and Asheesh Laroia, who runs OpenHatch. In what was ultimately a successful event, we had a structured system that works, and can serve as a template for similar sprints.
We did a fair amount of prep work, including going through the tutorial, looking for potential trouble where beginners might become confused. Additionally, we created a system for tracking suggestions to fixing the documentation. But, most importantly, we set up clear goals to help us, the organizers, stay on track:
1 Create a welcoming space for people to follow the Django tutorial, and help them successfully go through the Django tutorial (with the remark that the ability to follow an online tutorial is in fact a skill of its own, worth practicing)
2. To motivate people to make contributions to an open source project by setting them up to succeed initially.
3. Create a collection of first-hand experiences with the Django tutorial, usable as raw data for someone else to improve the Django tutorial
What made this work, ultimately, was were several factors:
0. We had clear systems in place for tracking questions and answers.
In order to support the goal of improving the Django docs based on user experiences, we needed to make sure people were tracking their questions and answers. We did this in two ways:
- We had bright red sticky notes available. When someone hit a snag as they were going through the tutorial, they would put one on their workspace as a way to signal to a mentor that they needed help.
- After their questions were answered, the hacker would make a note of the answer, and then write it up in the shared cheat sheet.
1. Brief, topical presentations that supported the goals.
We kept these limited to what was essential, and spread them out so information was given as it was needed, and there wasn’t a lot of interruption to peoples’ workflow. Here’s what we had:
- A mentor gave a fifteen minute presentation on an broad overview of Django at the beginning of the sprint.
- Right after lunch we had a group check in to field questions, and I gave a presentation on an diagram of how the Django engine works to those who wanted additional information.
- On Sunday afternoon, I presented on ReST and Sphinx, which are the fundamental tools for document editing in open source. Here I am with the balloonicorn:
2. Sufficient support
We had a 5:1 ratio of hackers to mentors, so everyone could get immediate help when the were hung up, and hackers pair programmed so they could talk their way together through the problems.
3. Funny hats for mentors
Mandatory. Else, how would people find us?
4. Shared resources
Our Django cheat sheet was a Google doc where participants shared new insight gained from mentors, suggestions for changing the docs, and additional resources for learning about Django.
Also mandatory. Can’t think without cupcakes.
6. Providing access to the right tools
Contributing to documentation requires a whole separate skill set that we didn’t have time to get into. Rather than delving into a tutorial on contribution tools, we set up a copy of Sphinx on my Github and asked participants to spend a half an hour writing up suggestions and making pull requests.
All of the hackers completed the tutorial and came away with new skills, everyone got fed, and the feedback on the event was overwhelmingly positive. We’re hoping to host these a few times a year to make Django more accessible to beginners.
To follow up, we still have to submit the proposed changes as tickets to the Django organization. Everyone had a great time, and the energy was hugely positive, and we managed to accomplish every goal! It took a lot of planning, but the amazing team made it possible. I believe it is not possible to make something incredible without a community, and this event was the result of a lot of a team effort. Many thanks to Angie of Hackbright Academy, who provided so much organizational support, to Amazon Web Services, who provided the food, Asheesh Laroia of OpenHatch, who knew how to make this open-source event a success, Jeremy Dunck, who represented the Django Organization, and all of the mentors who showed up.
All photos by Angie Chang.