6 reasons journalists should ‘show your work’ while learning & creating

In a busy corner of the metajournalism world, a crowd of journalists is assembling what amounts to a public, open-source curriculum on how to do hacker journalism. In blogs, tweets, Git repositories, meetups and slide decks, they’re sharing code snippets, tutorials, data sets, How To’s and more, in ways that are often engaging and accessible to non-geeks.

If I lost you at “Git repositories,” let me back up a step. The process of becoming a hacker journalist is different for everyone, but the pattern is common. Eventually the tools of writers cease to be enough: Microsoft Word gives way to Excel, which gives way to MySQL. And then, almost without knowing it, you’re creating the tools yourself. Having conquered English, you start learning a few phrases in HTML, then PHP, then Python and Django. One day without warning, you find yourself tromping around a Git repository.[1] And liking it. A new journo-hacker has been born.

Right now, journalists just like you are publicly documenting their own process of learning and creating. And if any part of you finds this compelling, there’s never been a better time for you to join in.

Why the “show your work” ethos is catching on

I should clarify a few things.

First, this practice isn’t primarily about teaching you how to become a [better] coder. That’s really just a nice byproduct.

And although there are many points of entry into this network of public programmers, it’s a distributed phenomenon rather than a coordinated campaign. Like many things in the git-’er-done-minded “hacker/coder/data journalist/computer-assisted reporter” community, it doesn’t even really have a proper name. But it does have something of a rallying cry, borrowed from your high school calculus teacher and spread by the fast-growing muckraker mob in Chicago: “Show your work.”

Lastly, it’s not really new. Journalists on the NICAR mailing list and members of IRE have been incredibly generous with their ideas and knowledge for years. Folks like Derek Willis and Adrian Holovaty have been sharing their ideas online for the better part of a decade (in Willis’ case, even longer). As Willis pointed out to me by phone, the NICAR/IRE newsletter Uplink has been going for two decades. Outside of journalism, the origins of this cultural ethic have an even longer history, reaching back as far as science itself (yep, that again), which developed the expectation that experiments should be well-documented. It’s baked into the fabric of the Internet, the “view source” culture that celebrates and rewards openness.

And yes, said Brian Boyer, of the aforementioned Chicago mob, math class probably played a part.

What’s novel is the somewhat sudden and very public uptick in this phenomenon: more journalists are sharing their work than ever before. In his farewell post for the Chicago Tribune’s News Apps blog (note the post title), PANDA Project lead developer Chris Groskopf says: “We’ve found ourselves in the midst of an exploding community of news-oriented developers who are hell bent on using, contributing to, and releasing new open source code. There are now more than a dozen active news nerd blogs–almost all of them producing new open source code.”

Why? Willis points to several reasons. The barriers to entry are lower all around from the days when Uplink and IRE conferences were your best bet, he says. It’s simpler than ever to throw up a blog or a Tumblr, and the basic tools necessary to do this type of work are becoming easier and easier to master, or at least to get dangerous with. Also, more networking opportunities for journo-hackers means that the IRE conference isn’t your only opportunity to meet up with fellow travelers. Now, there are Hacks/Hackers meetups happening across the world, and most folks in this universe are in daily contact on Twitter and elsewhere online.

Another reason, says Willis, is that “we realize that our problems aren’t just our problems anymore, and maybe never have been just our problems.” While journalists used to imagine that their challenges were fairly unique, we’ve come to understand that we don’t have a monopoly on the need to gather, organize and sift through data, or to manipulate and visualize information. As the lines between media organizations and software companies have begun to blur, coders at news orgs and coders elsewhere have discovered they have a lot to share with one another.

Plus, once this movement started to get a foothold, whatever cultural resistance might have prevented newsrooms from opening up their processes and toolkits to potential competitors started to wither away. Now that organizations from the New York Times to the Bay Citizen to ProPublica to the Guardian are showing their work, it’s easier for coders in every newsroom to say, “We should do this too.” (Everyone I spoke to said that whatever resistance there might once have been to these ideas is pretty rare to find nowadays.)

I might also point to the rise in prominence and respect for journo-hackers in the newsroom as a reason more and more journalists are learning to code in public. Although there remain a few benighted corners of the industry where folks are still asking whether coding can be journalism, these skills are now in high demand in newsrooms both big and tiny. Michelle Minkoff — a freshly minted Associated Press programmer whose coding career began two years ago in Willis’ class at Medill — told me over the phone that she’s excited to have started in the industry at this time. While coders used to have to fight for their place in the newsroom, in Minkoff’s experience, the coders are — if anything — too much in demand. Everyone in the newsroom wants help with a data project.

Six reasons to show your work

If you’ve read this far, you’re at least curious about this incursion of coder culture into the newsroom. Possibly you’re already a programmer yourself, or maybe you’re an aspirant to the title. Or maybe you’re a dyed-in-the-wool narrative journalist who wouldn’t touch anything called a “LAMP stack” even with biohazard gloves. With an assist from my conversations with Willis, Minkoff, Boyer and his team member Joe Germuska, I’m going to argue that you too (yes, even you, Gay Talese) should be showing your work. [2]

Keep in mind that documenting your discoveries and creations is time-consuming work; Boyer said a typical post laying out the process can take an entire work day to write. So why should you do it? I’ll present you with six arguments — three for the altruists among you, and three for the purely self-interested.

For the altruist

1. It’s only right to pay it forward. Whether or not you know it, you’ve benefited from others who’ve shown their work. This article you’re reading was published by an open-source CMS, using open-source database software. There’s a better-than-even chance you’re using an open-source browser to read it. As Germuska points out, the Internet was built by people saying, “Here’s what I did. How might it work for you? Make it better.” And certainly, if you’ve learned to code or you intend to start, you’ll have relied quite a bit on the kindness of strangers. What goes around should come around.

2. Your journalism can have a greater impact. When ProPublica details exactly how to go about replicating one of their prizewinning investigations, they empower other journalists, and even interested non-journalists, to put their good work to use in other contexts. Anytime you write a story, Germuska says, you necessarily filter the underlying data to support your narrative. By going public with the unfiltered data and the instructions for manipulating it, you sow the seeds for many more stories to be told. Others might find completely different stories using either your methods or the material you left on the cutting room floor.

3. Strike another blow for tech and data literacy. As Douglas Rushkoff says, “Program or be programmed.” The more we demystify this universe of variables and algorithms, the more agency we all have in a world increasingly run by software.

For the egoist

1. Do it for what Brian Boyer calls the “HR benefit.” Whether you’re a boss or an employee, showing your work raises your profile, giving you a strong boost in the hiring game. News organizations are competing for talent against tech firms offering bigger salaries, nicer benefits and foosball, Willis points out. But giving top-notch candidates a chance to do influential work that other programmers can emulate or extend makes your offer sweeter. And if you’re looking for a job yourself, sharing your knowledge and code is a terrific way to be on a hiring manager’s radar when a spot opens up.

2. It’s a force multiplier. Share your code with the world, and you open up the possibility that others might help to extend and support your work. Even if you’re not building the killer app that will fold the world’s laundry, sharing your discoveries and challenges increases the likelihood that others will chime in to help you with those challenges. Boyer and Germuska shower reverent words of praise on a Swiss army knife of data manipulation called CSVKit, developed in large part by Groskopf in response to a tweet from Germuska.[3]

3. It helps you learn. Everyone I spoke to said some version of this. Boyer put it best: “If you can teach something, you know it.” The task of documenting what you’ve discovered and built helps to organize and cement that knowledge in your head. And it helps your organization learn as well. Boyer describes it as a way to preserve institutional knowledge. “Chris [Groskopf] doesn’t work for me anymore,” Boyer says, “but I still have all his blog posts, and that’s going to be helpful for me.” The posts, he says, have become training manuals for whomever follows in Groskopf’s footsteps.

The curriculum

There’s not really a syllabus of required show-your-work reading. Once you start to dip your toe in the water, you’ll realize how many different directions you could go in both developing and democratizing your skills. But here are a few terrific places to start:

101-level course: Few journo-hackers are more approachable than Lisa Williams, who’s been running a terrific Tumblr since last May called “Life and Code.” Williams  writes just like she talks — pithy, casual and unassuming. Also, she’s a wife, mother and entrepreneur, so she knows something about having too little time. Start reading “Life and Code” from the beginning and you’ll find posts about how it feels to start out in this universe, important lessons that longtime programmers often forget to mention, and links to helpful resources. If you want the tl;dr version, begin with her post, “Learning to Program for Journalists: The Epic How-To,” which is an excellent starter pack for the would-be coder. If you want to find code snippets, head to Williams’ Git repository. Pair your reading of “Life and Code” with a trip to the much-ballyhooed Codecademy.

Upperclassmen tutorials: I generally find blogs by individuals a bit more novice-friendly than those by organizations. So if you’re still not feeling quite ready to storm GitHub, spend some time with self-described “protojournohacker” John Keefe. Willis, Boyer and Minkoff all maintain outposts online. And I’ve got to throw in a plug for my NPR colleague Chris Amico. Peruse the comment threads and blogrolls on these sites, and you’ll start to have a good idea of the network. And here’s the nice part about blogs: if you want to get a sense of the individual’s development, start with the oldest posts and move forward through time.

By this point, you’re ready to join the journo-hacker community; after all, you’re already familiar with some of its leading lights. Find the nearest Hacks/Hackers chapter, or start one. Begin your own show-your-work Tumblr.

Graduate-level work: At this point, approachability probably isn’t what you’re after. It’s code. Pure, glorious code. Unsurprisingly, you’ll find quite a bit of it on the Chicago Tribune’s News Apps blog. ProPublica, the New York Times, the Guardian, and the Washington Times and feature a particularly robust selection of tutorials and code snippets. Because DocumentCloud is a force of nature in the data- and document-processing world, DocumentCloud’s blog is also stellar, even if it’s all about DocumentCloud software.

If you can grok the work that appears on these blogs, congratulations. You’re a coder, no modifier necessary. And chances are you’ve already made your way to the universe of show-your-workers that stretches far outside the bounds of the Fourth Estate. Hopefully, you’re sharing what you’ve learned and what you’ve built. And perhaps you can also help me spread one more message:

All journalists should show their work. This movement, spread by hackers with hearts of gold, shouldn’t be confined to the realm of coding in journalism. Narrative journalists can do it. So can editors at The Atlantic. I try my best to do it. And so should you.


[1] Git is software that manages revisions to files. It allows you to do things such as view previously saved versions of files, or work on a file in tandem with others. A “Git repository” is just a collection of files managed by Git. For more on version control software, check out this friendly guide.

[2] I should point out that when Boyer and Germuska talk about showing your work, they’re talking not only about the act of documenting what you’ve built or learned and how, but also about the act of open-sourcing your work – making your code and data available for the world to use.

[3] If you don’t mind being a little out of your depth (and you shouldn’t) and you’ve got a basic familiarity with the command line, take Brian Boyer’s advice and check out Chris Groskopf’s surprisingly readable tutorial for CSVKit.

This story is also part of a Poynter Hacks/Hackers series featuring How To’s that focus on what journalists can learn from emerging trends in technology and new tech tools.

We have made it easy to comment on posts, however we require civility and encourage full names to that end (first initial, last name is OK). Please read our guidelines here before commenting.

  • Anonymous

    First a thanks to posts like this, and all those mentioned in it, and Mr. Boyle as well… The last eight months or so of paying attention to, learning from and experimenting with everyone has been one of the most best learning experiences of my life – not saying much for a college dropout, but come on now.

    Second, if you are in to Twitter lists, you can find many of the folks showing their work here: http://twitter.com/#!/list/ChrisLKeller/coworkers-inspiration 

  • http://twitter.com/andymboyle Andy Boyle

    And for any aspiring journalists who wish to start learning about the fundamentals of the internet, here’s a post I wrote trying to walk you through all the bits and showing you where you can learn more: http://www.andymboyle.com/2011/07/11/learning-to-make-the-internets-a-journalists-guide/

    Or if you’d like to take a shot at setting up a quick news app on a production server while I hold your hand, you can do that here: http://www.andymboyle.com/django-tutorials/