Lessons learned from running doc sprints

5 lessons from the Open Help doc sprints

Typewriter keys
Image credits : 

Original photo by mshipp. Modified by Rikki Endsley. CC BY-SA 2.0.

Sprints are one of the most effective tools for building momentum and community around an open source documentation project. For the past four years, the Open Help Conference & Sprints has hosted doc sprints for a number of prominent open source projects, and often has been the first sprint venue for a project. Open Help celebrates its fifth year in 2015 with a venue upgrade and space for six doc sprints.

Open Help has a unique format that includes presentations as well as attendee-led open discussion. Open source projects face unique challenges, and the discussion format allows people to ask questions and share solutions on everything from content planning to building community.

Perhaps more importantly, though, Open Help hosts three-day doc sprints for open source projects. Open Help handles all the logistics, freeing people up to focus on their content and their community. What's more, having sprints alongside other projects affords the opportunity to learn best practices from other teams.

Past sprints

In its first year, Open Help hosted sprints for GNOME and Mozilla. Both GNOME and Mozilla had had sprints before, but not many. Open source doc sprints were fairly new at the time, and watching the different team dynamics was interesting. Mozilla contributors were generally quiet and diligently writing, interacting mostly for reviews. GNOME contributors, on the other hand, spent much of the time planning and brainstorming. Both teams were productive, and both have gone on to hold many more sprints and refine their process.

In 2012, Open Help hosted sprints for GNOME, FreeBSD, and WebPlatform.org. In fact, Open Help 2012 happened before WebPlatform.org even launched. Community members from Mozilla, Google, Microsoft, and the W3C came together to plan a definitive reference for the web as a development platform. This was a fantastic example of collaboration and cooperation, with contributors from multiple companies and organizations that were already maintaining their own reference sites for the web.

In 2013, GNOME and FreeBSD returned and were joined by WordPress and Wikipedia, as well as a Mozilla contributor. The Wikipedia team created a best practices guide for Wikipedia's help pages, and they applied what they learned during the conference to the Wikipedia Teahouse, a support space for new editors. Additionally, key contributors from OpenMRS joined for the first sprint day to plan their documentation.

Last year saw a return of contributors from GNOME, FreeBSD, and Mozilla. For the first time, the GNOME team shifted its focus from user help to developer documentation, leading to the successful HowDoI set of developer tutorials.

Sprint tips

Holding a successful doc sprint requires some thought and planning. I've been involved in fantastic sprints, and I've been involved in sprints that were completely unproductive. There is no single formula that is perfect for every community, and as you hold more sprints you'll learn what works best for your team. Here are some tips I have from my years of experience organizing sprints and observing other people's sprints at Open Help.

  1. Be proactive. I've seen a lot of potential sprints never happen because nobody pushed for them to happen. In a project like GNOME that has a regular rhythm of hosting sprints, getting people to attend is fairly easy. But if your community members aren't used to attending sprints, you'll probably have to be a bit pushy to get them to commit to join.

    Funding is always tricky for volunteer-heavy projects. Often a foundation or a sponsoring company has funds to help contributors attend sprints and other events, but organizers face a chicken-and-egg problem: Contributors won't commit to attending without funding, but sponsors can't commit funds until they see an attendee list. Identify the people you want to attend and push them to commit contingent on funding. Emailing people individually helps. Set up a wiki planning page with names of potential attendees, and use that when asking for funds.

    Having a sprint at an event like Open Help means you don't have to worry about venue expenses, but travel and lodging are still concerns.

  2. Have an agenda. Do not walk into a sprint with no idea of what you'll be working on. Use mailing lists or a wiki beforehand to talk to fellow contributors and decide what needs to be worked on. Remember, even people who aren't able to attend can help craft an agenda for the sprint.

    Although having an agenda is important, don't be too specific, and don't be too strict about following it. Knowing what problems you're trying to solve and which parts of your documentation you're trying to improve is helpful. In fact, this can often affect who you most want to attend. But sprints have a way of bringing out new ideas. Don't be afraid to follow them just because they're not on the agenda.

  3. Make sure everybody is prepared. One of the fastest ways to derail a sprint is to spend the whole time getting people ready to contribute. If people need to have specific software installed, or need to be familiar with certain technologies or processes, let everybody know beforehand. Sometimes a sprint can be a useful way to onboard people, and in that case you may not expect everybody to arrive ready to write. Just be sure to set the right expectations.
  4. Focus on planning. This isn't an absolute. I've seen many sprints that successfully focused on writing instead of planning. But in my experience, collaborative planning sessions are a better use of face time, for two reasons.

    First, writing is easier to do alone than planning. People can write well when they go home, but they won't plan as well as they could have together during the sprint. Intense writing sessions are good for virtual sprints, where people don't meet face to face. But when you're sitting in the same room as each other, it's much easier to find problems and figure out solutions.

    Second, planning sessions build better communities, because they tend to be more interactive than writing sessions. Successful sprints build community as well as create good documentation, because your community is the key to your success after everybody goes home.

  5. Spend time together. Different teams have different expectations for how long people will work during a sprint. Some teams only work a normal work day, whereas others work well into the night. Either way, sprint attendees should spend as much time together as possible, whether that time is spent working or playing.

    Plan to have meals together. Go to bars or coffee houses together, depending on what's comfortable for your community members. If you have time, take an excursion together. Walk the city, visit a museum, or go to a comedy club. Get to know each other. Have fun. Social bonds are the most important thing your team can create.

Sprint at Open Help

You can hold a sprint anywhere and any time. But Open Help is a great venue for your team sprint, especially for teams that haven't held a lot of sprints before. In addition to having a fun and productive sprint, you get to learn from the collective experience of teams that have been holding sprints for years.

If you're interested in a sprint at Open Help, email info@openhelp.cc. We can help you put together a successful sprint. And if you have anything interesting to share, you can submit a proposal for a full-length talk, or just a 15-minute brief or demo. Open Help is only successful because of the people who attend, and we always like to hear new insights.

Doc
Dish

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.