The Field Guide to Open Source in the Newsroom
Journalists who work with code know how open-source projects pay off. When we share tools that solve common problems, we work faster and spend more time covering the news. Releasing projects to the public puts more eyes on our code, and makes it better.
Doing that work isn't easy, though. Newsroom deadlines often don't leave time for cleanup and documentation, much less the planning that leads to reusable code. In newsrooms where open source isn't the norm, it can be hard to make the case for "giving away" your work. A common set of cultural and technical questions come up before, during, and after every open-source release-but as a community we don't have a common pool of answers.
But we can build one together.
About this Guide
This guidebook collects the advice and experience of dozens of newsroom developers and technologists, covering the entire open-sourcing process—from starting a project to handoffs and sunsets—in the context of journalism. It's a collaborative resource that will continue to grow. We'd love to have you contribute, and share the great work you're doing with the rest of the journalism-code community.
The guidebook is hosted by OpenNews, a team that helps developers, designers, and data analysts convene and collaborate on open journalism projects. The first draft was written during a two-day event in December 2016, with about 20 people working in-person and remote.
Table of Contents
- Chapter 1: Choosing Open Source, and Getting Buy-In
- Chapter 2: Starting a New Project
- Chapter 3: Opening Up An Existing Project
- Chapter 4: Code, and Getting To The First Release
- Chapter 5: Documentation
- Chapter 6: Working With Community
- Chapter 7: Managing Releases
- Chapter 8: Handoffs and Sunsets
- Contribute to this guide
The Field Guide to Open Source in the Newsroom is written by people who care about journalism, specifically to address the cultural and technical challenges faced by developers who work in newsrooms. There are other wonderful guidebooks to open-sourcing
- Open Source Guides from GitHub
- "Producing Open Source Software" by Karl Fogel
There's also a companion tool to this guidebook. Open Project Linter is an automated checklist you can use to test project directories for good practices in documentation and code. (And it's an open-source project you can contribute to as well!)
This is a community resource, and it gets better every time anyone from the journalism-code community shares advice, writes up an experience, asks a question, or even just spots a typo. We'd love to add your voice to this project, and here's how you can join in.
This project includes ongoing efforts to localize for readers in:
- Spanish (initial translation by Barbara Maseda—thank you, Barbara!)
Want to know more about this guidebook? Have a question about open-sourcing a newsroom project? Reach out to email@example.com.
The following people have contributed to this guidebook:
- Kaeti Hinck
- Jeremy Bowers
- Kavya Sukumar
- Sumana Harihareswara
- David Forbes
- Jane Friedhoff
- Adam Schweigert
- Alan Palazzolo
- Katie Park
- Amanda Wegrzyn
- Ændrew Rininsland
- Bissie Anderson
- John Heasly
- Bradley Fields
- Daniel Bachhuber
- James Gordon
- Mallory Busch
- Ted Han
- Ryan Sholin
- Derek Willis
- Lisa Charlotte Rost
- Jacob Harris
- Ryan Pitts
- Lindsay Muscato
- Erin Kissane
- Noah Veltman
- Aurelia Moser