Editorial transparency in computational journalism

Benefits of editorial transparency

Releasing documented code and data does sound like extra work, and it is. But by investing this extra time, we benefit ourselves, our field, and our readers.

Writing code that others will see, and potentially criticise or question, encourages us to write cleaner code, with appropriate commenting, logical organisation, and visualisations.

Adopting this process ensures that what we are reporting is based on evidence, and that this evidence is present and correct. And when our code and data are open, as with most open source fields, rapid development within that field occurs.

The field of journalism benefits from an educational standpoint, where journalists can learn from clear, well-documented code. Journalists can access the data and create something new from it that they had not considered, had no time for, or to tell a local story.

Editorial transparency also benefits our readers. Particularly in these times, establishing and maintaining trust with readers is tantamount to the continued success of journalism. Part of building that trust is enabling readers to check your work or see the steps that lead you to your story, facts, and conclusions.

Just as we cite our sources, we should provide evidence for our data journalism also. We allow readers to engage with our work more by providing the code and the data, as well as the opportunity for new stories, or even corrections if errors are found in our code.

Case studies

For example, below are two case studies of my own work using transparency tools that are free and open source.

Here’s how we ran the project to promote transparency:

• code is available on GitHub
• usage and customisation instructions and documentation are available in the README.md file
• the tool is independent of platform (Mac, PC, Linux) -- all that is necessary to create one’s own bot is to install the required python libraries, edit the configuration file, and run it on a server like AWS.

We aimed to make our tool as accessible to others as possible, so that any newsroom or individual could make a copy of the code, and customise the configuration settings to create their own bot. It was challenging to discern how much customisation to build into the tool, while ensuring that it wasn’t so flexible as to render it too complicated or to dilute the specific goal of the bot.

Other news organisations’ Github examples:

• Buzzfeed News often share their data analysis, libraries and tools on their GitHub account, including their recent story about spy planes
• ProPublica shares many tools and stories, including one on machine bias
• Economist Data Team mostly shares their JavaScript-based visualisations and data

These are just some examples of newsrooms sharing, although not all of them come with documentation or links to the articles they were published in. Remember: simply sharing code is not equivalent to transparency.

Documentation

What does documentation entail?

• Journalists should comment on code, explaining what each line, code block, or function does.
• Writing code in Jupyter Notebooks can be helpful if the project is in Python, R, or Julia, as HTML and Markdown text can be added in between code blocks to provide context or explanation. Graphics can also be displayed inline with the code, and it can be viewed online without requiring you to install specific software.
• Write a README.md for your GitHub repository that provides context for the study, links to the article and to the data, a list of code dependencies (that is, which code libraries were used), a data dictionary, and any other information that may assist someone in following the code. Consider linking to these within the news article.
• Try linking to reference material for any APIs or external software used.

This saves you from re-writing instructions on how to use these APIs. For example, the comment bot collects comments from Disqus forums and, rather than explaining how to set up a Disqus API account, I referred the reader to the Disqus documentation.

Considerations when sharing

Each project will have its own unique considerations. Sometimes sharing the data in its raw form will not be possible because of privacy issues. In these cases, it might be possible to share aggregated or cleaned data that no longer contains personal identifiable information. In other cases, the data used may be proprietary or have been provided to you with restrictions or an agreement. Sharing this data will of course not be possible, and a statement could be made to that effect. If the data itself cannot be shared, still consider sharing the code used to clean the data and analyse it. If any graphics in the article were created using code, share that too.

Licensing

Sharing code is great, but for others to use your code, it has to come with a licence. There are many different ones to choose from depending on whether you’re sharing code, data, or a mixture of the two.

Check out these links to help you choose:

• Code
• Data
• Mixture

For more detail on building transparency and accountability in computational journalism, read the full research paper here.