Design the data model

[simonw]

This repo will store examples of journalists publishing their workings - data, code and methodology - behind the stories that they report.

First step: figure out the data model.

[simonw]

It's not quite as simple as a "story" - because one of these things could spin off multiple stories, and one story might have multiple GitHub repos / methodology explanations behind it.

Maybe "project" is the right term here. Or "investigation"?

[simonw]

I'll use https://github.com/wpinvestigative/helicopters_dc as a simple example.

An investigation could have a required name and an optional description:

• Name: A low-flying ‘show of force’
• Description: The Washington Post story A low-flying ‘show of force’ focused on two military helicopters that roared over demonstrators in Washington D.C on June 1

It can have multiple stories (articles?). Here that's https://www.washingtonpost.com/graphics/2020/investigations/helicopter-protests-washington-dc-national-guard/ - "A low-flying ‘show of force’", which has a headline, a byline and a publication date.

It can have one or more repositories/notebooks/explanations/assets? Really not sure what to call these or how to group them. In this case those include:

• The GitHub repo: https://github.com/wpinvestigative/helicopters_dc
• Three notebooks: https://wpinvestigative.github.io/helicopters_dc/01_adsb_altitude_adjustment.html and https://wpinvestigative.github.io/helicopters_dc/02_leaflet_helis.html and https://wpinvestigative.github.io/helicopters_dc/02_leaflet_helis.html

It has contributors. In this case the byline on the story has Alex Horton, Andrew Ba Tran, Aaron Steckelberg and John Muyskens. The GitHub repo has two contributors: andrewbtran and jmuyskens - both of whom are also in the story byline, but I could imagine situations in which some contributors don't get included there.

This is pretty complicated already! And this is for a simple case where there's one story and one GitHub repo backing it.

[simonw]

Some other, more complex examples:

• The Washington Post Opioid Files: https://www.washingtonpost.com/national/2019/07/20/opioid-files/ - lots of stories, an API with the data in it
• https://github.com/fivethirtyeight/data - a single repo containing data for stories going back several years

[simonw]

I like the term "investigation" for the main entity.

An investigation can have multiple contributors, multiple stories and multiple assets (repos, notebooks, explainer articles etc).

I'm not sold on "assets" here. What's a good name that could encompass all of the following?

• GitHub repos
• Published data
• Articles about how the story was reported, e.g. https://themarkup.org/locked-out/2020/05/28/how-we-investigated-the-tenant-screening-industry
• Notebooks
• Anything else that isn't exactly a story but does help explain the working behind the story

[simonw]

https://nieonline.com/coloradonie/downloads/journalism/GlossaryOfNewspaperTerms.pdf may be useful.

[simonw]

reporting or reporting_artifact perhaps.

[simonw]

I'm going with artifact. If a better name shows up later I'll switch to that instead.

[simonw]

Data model as YAML:

title: A low-flying ‘show of force’
description: The Washington Post story A low-flying ‘show of force’ focused on two
  military helicopters that roared over demonstrators in Washington D.C on June 1
stories:
- headline: A low-flying ‘show of force’
  byline: Alex Horton, Andrew Ba Tran, Aaron Steckelberg and John Muyskens
  publish_date: 2020-06-23
artifacts:
- title: wpinvestigative/helicopters_dc
  url: https://github.com/wpinvestigative/helicopters_dc

Transformed to JSON that looks like this:

{
   "title": "A low-flying ‘show of force’",
   "description": "The Washington Post story A low-flying ‘show of force’ focused on two\nmilitary helicopters that roared over demonstrators in Washington D.C on June 1",
   "stories": [
      {
         "headline": "A low-flying ‘show of force’",
         "byline": "Alex Horton, Andrew Ba Tran, Aaron Steckelberg and John Muyskens",
         "publish_date": "2020-06-23"
      }
   ],
   "artifacts": [
      {
         "title": "wpinvestigative/helicopters_dc",
         "url": "https://github.com/wpinvestigative/helicopters_dc"
      }
   ]
}