A guide to our open-source storytelling tools.
Latest commit c727b8e Feb 5, 2015 @cadamez cadamez Update README.md
Fixes issue #1
Permalink
Failed to load latest commit information.
README.md
flowchart.png
git-commands.png
more-git-commands.jpg
new-repo.png
newsroom.md Update newsroom.md Nov 19, 2014
terminal.jpg

README.md

Mother Jones's Storytelling Tools

Index

List of tools

How we work

Important caveat: This walkthrough isn't going to be very useful to non-MoJo folks. All of our spreadsheet templates are publicly viewable and copy-able, however.

Here's an overview of how we use these tools at Mother Jones. Step-by-step instructions are below.

Most of our tools are powered by Google Spreadsheets. We have sample spreadsheet templates that you'll copy and modify for your story.

Next, you'll use the command line to make a copy of the tool you want from our Github library. This copy will live on your machine, or "locally." Then, you'll use a text editor to match it up with your spreadsheet.

Once your "local" version of the tool is working properly, you'll upload it to the cloud using Amazon Web Services S3, a cloud-based file-storage service, where it becomes publicly viewable.

Finally, you'll embed this public version of your project in an article via our CMS.

screenshot

Setting up your machine

To use these tools, there are a few things you'll need to download or set up on your machine.

  • Admin access on your machine. Talk to Ross.

  • A good text editor. We prefer SublimeText.

  • You'll be using the command line to access our GitHub account. All Macs have a built-in command line program called Terminal. You can use that, but we prefer iTerm2. Download it.

  • We use GitHub for "version control," or keeping files neatly organized and easy to ctrl+Z if anything breaks. Talk to Ross about downloading Git and setting up a new GitHub account for yourself, and connecting GitHub to your computer following this guide.

  • Finally, you need to link your account to the Mother Jones GitHub account. Talk to AJ.

  • S3 Organizer, the Firefox plugin for uploading to Amazon S3, a cloud-based file storing service, as well as access to our files on s3. Talk to Robert.

  • The shared Mother Jones Google Drive folder. Talk to AJ.

Some good background

The tools, languages, and concepts you'll encounter when working with these tools might be totally new to you. Here are some good backgrounds:

Starting a new project

1. Upload your data

Go to the Github page of the tool you want to use. Read through the README, then open the Spreadsheet Template link. When it opens in Google Docs, go to File > Make a Copy. Give your project a working title.

File > Move to Folder > Mother Jones Drive > folder for your beat. Make Mother Jones the owner of the spreadsheet under Sharing > Owner.

Replace the data in the spreadsheet with the data for your project. Check the README for specifics.

File > Publish to the Web Publish just the sheet with your data. Make sure that automatic republishing is turned on. Notice the URL that's created after you hit Publish; you'll need that later.

2. Make a copy of the tool

Create a new private repo under the Mother Jones account (how-to).

screenshot

Name it with the slug of your story + the name of the tool, i.e.: rape-statutes-map-table.

Now you're going to make a copy of the tool you want to use and stick it in the new repo. Here's a screenshot of all the commands you'll need (replacing your repo names as needed). The portions that are blacked out are messages back from the terminal.

You can also find the same commands here: (how to).

screenshot

In SublimeText, open the main folder of your repo. At this point, go check out the tool's own README page for further instructions.

As you make changes these changes, you need to update your project file's on GitHub to match what you're doing on your own machine (essentially saving as you go). Check out these tutorials for a basic intro to GitHub commands:

Here are the commands you'll use over and over:

  • cd open and go into a folder on your machine

  • git status check to see if you have unsaved changes

  • git add --all add all your changes to be saved

  • git commit -m "Message here" decribe your changes

  • git pull check that no one else has uploaded any new changes

  • git push finally, upload your changes to GitHub

This screenshot shows the process of making a couple sets of changes and uploading them to GitHub:

screenshot

3. Upload to s3

Open S3 Organizer in Firefox. The left-hand pane shows files on your machine (aka "local"). The right-hand pane shows files in the cloud. Upload your local files to the right place in the cloud. Notice the icons in the top-right corner of the screen; you use these to move around, make new directories, and so on.

After your files have been uploaded, right-click on the main project folder. Edit ACL and change the permissions as needed. Click "Apply to subfolders" to change all your files at once.

Finally, right-click on your index.html file to copy the distribution URL (you want the one on the bottom). You'll need this in the next step.

4. Embed in the shell

We use Pym.js to embed projects into stories via our CMS. Here's what you need to put in the Source view:

  <div id="graphic"></div>
  <script type="text/javascript" src="http://assets.motherjones.com/interactives/plugins/pym.js/src/pym.js"></script>
  <script>
        var pymParent = new pym.Parent('graphic', 'replace.html', {});
  </script>

Your distribution URL goes in the place of replace.html. Check that things are working in the latest versions of Firefox, Chrome, and Safari, and test on an iPhone 4 or later as well.

5. After publishing:

  • Replace the working title of your spreadsheet with the headline on your published article
  • Convert private repo to public
  • If you made happened to make useful design improvements to the tool, talk to Tasneem about potentially making these changes to the master version as well.

Coordinating with the newsroom

Of course, stories involve a lot more than spreadsheets and html files. Here is a list of non-technical but very important editorial concerns when it comes to publishing your story:

Editorial needs