Documentation requires breathing room: time and mental space to reflect on a project, retrace steps, and turn a heap of choices into readable notes and instructions. None of that comes easy, especially in busy newsrooms. OpenNews tries to help the community carve out time for that work through small events called code convenings, where journalists and developers take two days away from deadlines to finish off, document, and release open source projects. Our code convenings have helped release dozens of new tools over the past three years, and make good documentation a top priority every time.

This year, OpenNews started thinking of applying this convening model more broadly. Rather than bringing people together to finish their disparate projects to work on, could we all document a single challenge that many newsrooms share? What would that kind of doc sprint look like? What challenge would it address?

Part of our mission is to experiment, so we settled on an issue that we hear a lot about: starting and running open-source projects. And because open-source software helps newsrooms spend less time writing code and more time producing important stories, that problem seemed especially important right now.

We imagined making a how-to guide for newsrooms interested in open-sourcing their code, and, spoiler: that guide now exists. The Field Guide to Open Source in the Newsroom was created over two days in Washington, DC, with about a dozen people in person and a dozen more working remotely. We’re thrilled with how it all turned out—eight solid chapters plus supporting material. But we’re equally proud of the process itself, and we think it can work for other doc sprints, too.

Speed Without Misery

Documentation often falls to the bottom of the to-do list, after all the momentum has been burned by a project’s final push. A doc sprint brings some of that energy back. At the same time, though, anything with “sprint” in the title suggests an exhausting process.

We wanted to build momentum without burnout, and OpenNews believes strongly that a successful event starts with thinking about humans. We try to make people feel cared for and safe, starting from a code of conduct and clear expectations for everyone. And we want people to feel like they’re free to focus on doing their best work, so we do our best to reduce stress and answer questions before they come up.

Short Event, Long Timeline

The sprint that created the Field Guide lasted just 2 days, but we actually planned out the work over about 3 months: 8–10 weeks of leadup, the in-person event itself, and weeks of follow-through.

That sounds like a pretty long timeline, but plotting your calendar way in advance is the first step toward a smooth doc sprint. Here’s our checklist for getting an event off the ground:

We actually have a GitHub issue template for this—it’s a little more complex than this list—but we really do start with the basics. Food and shelter might seem obvious, but there’s it’s worth it to sweat the details.

Food is something that’s easy to overlook. Most of us have been to events where meals and snacks are thoughtful and timed right…and we’ve all been to events where food and hydration is an afterthought. It’s remarkable what kind of difference that makes in how well you feel like you can get things done. So we look into our food options early—what’s nearby and walkable, who delivers. Will we have any dietary needs in our group? What restaurants can handle those? Oh, and where’s our coffee going to come from. (That’s a separate checklist all its own.)

Finding the right workspace is important, too. When you invite people to lock themselves in a room for a couple of days, having a human-friendly space is crucial. You’ll want a room big enough for people to break into small groups, or to split off solo for quiet work. You’ll want walls or windows or whiteboards where you can put up Post-Its, if, like us, you use a metric ton of Post-its. You want a place that’s okay with allowing food and drink in the room. You also want natural light if you can get it…it makes a huge difference when you trade in fluorescents for some nice big windows.

And if you happen to be bringing people in from out of town, you’ll want to get a handle on what’s available and how expensive lodging will be before you pick a location—you might not want to land in a city at the same time as a festival that’s going to sell out every reasonably priced hotel.

Those two places, workspace and hotel, are where your participants are going to spend most of their time, so nailing down great spaces early on goes a long way to lowering anxiety about participating.

Food, shelter, coffee. When you put real thought into the basics, you free up everyone’s brains to think about the things you want them to.

Communicate Early and Just Often Enough

The communication pattern that we’ve found to be most helpful is to give updates every week or two, and to stay relentlessly focused on desired outcomes—what can participants be thinking about right now to make this event productive. We keep emails focused and short.

Another of our old standbys: We always point back to a reference document that has all the facts about participation. We just use a shared Google Doc for this, but it’s so helpful. Ours includes:

• A couple of paragraphs on what the event is about—something participants can share with bosses or colleagues
• A loose schedule for the event days, so no one has to wonder about when to show up, or when meals are happening
• Address and details about the workspace and hotel, including transit tips
• All the participant names and a place to share contact info if they want – we want people to feel like a cohort, and this is where it starts
• Relevant project links or repos
• Instructions about expenses

This document is a lot like something you’d find on a website for a conference, and it’s worth taking the time to make it, even if it’s just for a handful of people. It’s a great signal that participants will be supported the whole way, and that logistics are under control.

One note on expenses: We try to make sure travel expenses aren’t coming out of people’s pockets. We have program funding set aside for this, but if we didn’t, we would absolutely look for sponsorship. It really expands the pool of people in the community who can participate.

In-House Homework

For the Field Guide, we also spent a lot of our lead time thinking about the content of the guide itself. We tried to answer three big questions beforehand:

• Is this a good idea? We at OpenNews felt like there was a need for this resource, a guidebook on open sourcing newsroom software…but did people in the community feel the same way?

• Who’s our audience? Are we making a thing for experts? For beginners? Are we writing for developers themselves, or for the people they work for?

• Is this doable? We’ve done plenty of convenings, but never one where the output was documentation—are two days enough to make something great, or is that too ambitious?

We didn’t want to ask anyone else to volunteer their time until we answered those questions, so we spent a couple of weeks doing research and talking one-on-one with people in our core community who run into the challenges we were thinking about. This work helped us verify that there was a big appetite for a resource like this, and a willingness to pitch in to make it happen. It also helped us figure out our audience: developers worried about a.) making the best technical decisions for their projects, and b.) navigating the conversations and community around open source.

To answer our third question—could we do meaningful work in a two-day sprint?—we had to do some writing of our own. Based on our conversations, we put together an outline for the guide that felt big enough to do a lot of good, but defined enough to get through in two days.

We ended up with a framework that felt “opinionated, but not definitive.” Creating that starting point let us start having productive conversations about the project, and it let us start them faster.

Choosing Tools Wisely

We made a few more decisions to kickstart the project—like what tools we’d use to write the documentation. We interviewed authors, checked out platforms, and read a lot about collaborative writing and book sprints, but in the end we stuck with a few simple tools that everyone knows.

• We used Google Docs for writing, because everyone has access and knows how to use them, and they have built-in comments for editors.
• We used GitHub for data storage, so we could use pull requests and issues to make good on the promise that this could be a living resource.
• We used Read The Docs because we wanted a more public-facing, reader-friendly version.

Having an outline and tools gave everyone a head start, and it also gave us a really good story to tell. We got to share how much thought and work we’d invested in the project already, and that gave us a lot of credibility as we started recruiting people to help us write.

And for the planning phase, that was the final piece of the puzzle.

We needed writers.

Recruiting the Writers

One thing that’s really important to us at OpenNews is that our events reflect the whole community we serve. We’re at the intersection of journalism and tech, and there are definitely underrepresented groups in both of those industries. If we want to run an inclusive event, we have to put in the work, and we do.

We put a lot of effort into outreach to make sure we have participants across gender, race, size of organization, even professional background when that’s appropriate. Having a great mix of people in the room means that you collectively ask better questions, come up with better answers, and make a better thing.

For the doc sprint, we designed our recruitment process to get to that goal. We started with one-on-one outreach, just to make sure we had a base of volunteers who could help pull off the project. And a couple months before the event, we launched an open call for participation and asked our community to help spread the word, because there’s always a ton of great people out there who we haven’t met yet.

Between those two things, we pulled together a fantastic, diverse group of people. Enough people to make two teams: about a dozen writers to work in-person, and a dozen more to work as remote readers and editors.

At this point, it really felt like everything was coming together. Food and shelter? Check. Project outline? Got it. Our group of volunteers? Ready.

Before you know it, you’re not talking about planning and theory any more, you’re all meeting up at the workspace.

Welcome to Your Doc Sprint

On the first morning of the sprint, our in-person writing team filtered in to NPR headquarters in D.C, making their way to a spacious, light-filled boardroom. Suddenly, after those weeks of planning, our carefully laid plans started coming to life, from the carefully curated snacks to the diverse group of smart people introducing themselves around the table.

The agenda was structured around blocks of about 45 minutes each, with writing slots layered between blocks for brainstorming, informal conversation, or downtime.

First up, we needed to get a sense of what information each chapter would contain. We had our pre-made, research-based outline as a starting point. After getting consensus on that outline, the eight headings became the titles on eight big pieces of chart paper. Then we taped all eight piece of paper on the walls around the boardroom. Each writer then jotted (on Post-Its) the many ideas and points that could fall into each chapter. Next, as a group, they clustered these under the appropriate headings. Each piece of chart paper became a repository of collectively generated notes about that chapter.

Collaborative writing starts with many, many Post-Its.

When it came to the writing process itself, we took a human-friendly approach, there, too. To make sure no one started with a blank page, we built a barebones template and copied it into each chapter’s Google Doc. The template’s elements came from some of our favorite docs, collected during our research phase: a compelling intro, useful examples, and easy-to-use checklists. We also gave everyone a style guide that encouraged writers to adopt the conversational tone and clear language that characterized our favorite docs in the wild.

With those support beams in place, the writers could focus on creating the all-important content for each chapter.

But how would they actually get words on the page, collaboratively?

We’d imagined implementing a pair writing process; maybe something like pair programming. One person would type and the other would dictate. But the closer we got to the event, the more this sounded like a bad idea. Wouldn’t it be sort of, I don’t know, awkward? To have someone over your shoulder? Or maybe it wasn’t awkward at all. Maybe it was exactly the kind of collaboration that every writer should always have, all the time. It was really hard to know what would work best for the team. So we decided to leave it to the writers themselves.

First, they gravitated toward the chapter they wanted to tackle first, and then we asked them to group themselves into pairs, or something close to pairs. One writer possessed a deep specialty and wanted to forge ahead solo, to lay that knowledge on the page. (We also had a trio, at another point. )

Next, they peeled their chosen chapter’s big repository of Post-It notes off the wall and spread it out near their laptops. From there, writers opened their Google Docs, where those pre-made chapter templates awaited their words. It was time to write.

As organizers, this was a satisfying moment. A hush fell over the room as pairs of writers murmured to each other. If you’ve ever run an event that’s something of an experiment, you’ll recognize the feeling of seeing your long-laid plans become real; a feeling of stepping out into what looks like thin air and realizing that the ground holds.

Working, working.

Those two days felt busy but not rushed—carried by the energy of making something, together, on the spot, and buoyed by all those human-centric perks we’d built in. At the end of day one, the Google Docs went to our pre-selected remote team, and we reviewed their feedback together the next morning. On day two, writers could finish what they’d started the previous day, pick up something new, or help each other with a sticking point.

We also took several pauses to reflect on whether this guidebook was meeting our audience’s needs, and whether the pair writing process was working for everyone. And of course, lunch and snacks. Always snacks.

The second day closed with a beautiful moment in which all the writers simultaneously and collectively wrote a README.

Ready, set, README.

Bringing it Home

The guidebook wasn’t completely done by the end of the second day— and we hadn’t expected it to be. But it was an incredibly rich repository of information, ready for more shaping. We kicked it over to the remote team for two weeks of editing, and then we internally smoothed those edits into a draft that felt ready for public sharing on GitHub and Read the Docs.

These days, we’re having conversations with newsrooms about how they might use this document, and we’re also still accepting contributions to make it better. (We’re particularly excited to see that it’s being translated into Spanish.)

A Model to Adapt and Try

This model worked well for the Field Guide, but we’d love to see more collaborative doc sprints take shape. Could this work for your next project?

Our big takeaways from this experiment:

• Test your idea with a few people you know
• Start planning early, and start with the basics
• Communicate well, and come up with an active facilitation plan
• Set aside time for follow-up work.

And throughout it all, think about human beings, not just about the work.

• Share on Twitter
• Share on Facebook