The New York Times’ “Snowfall” is one of the most influential digital news projects of the last few years. The immersive approach to storytelling — photos that went from edge-to-edge of the screen, infinite scroll, embedded gifs and videos that “fly” the user through the terrain of the story — were and are very captivating. Snowfall is about an avalanche that traps a group of people in a remote mountainous area, and it’s well worth reading even now. Check it out here.
This tutorial will show you how to take your material and transform it into a tablet-friendly, rich experience for readers. We will use open-source software called sStory, created by EJ Fox.
0. Ask yourself: is this the right story for this format?
This tutorial was inspired by my Australian journalist friends, who came to a workshop I taught hosted by The Walkleys Foundation. (The Walkleys are also Australia’s most prestigious journalism awards, akin to what the Pulitzer Prizes are to American journalism). The participants in the workshop were unfailingly bright and willing, and so we skipped through several data visualization lessons early and spent the last half of the last day of the workshop trying to pull together our work into a data-driven, immersive story. As part of our process, we had a story meeting where everyone pitched story ideas. We quickly came to the conclusion that not every story really “fit” this format. In particular, we were looking for stories that had:
- A data element — charts, graphs, maps (not all immersive stories would require this, but it was a data-visualization workshop)
- An audio-visual element (video, audio)
- A narrative approach
- Compelling photos that would look good at larger sizes
Not all of the stories had all these elements. A story on taxation, for example, might simply not be visual enough for this kind of treatment.
Here’s another great example of a story done in an immersive, tablet-friendly, scrolly way, done by WBUR, a public radio affiliate in Boston:
The story covers the trial of a colorful criminal who ran much of Boston’s organized crime and then went underground and managed to elude capture for decades. Embedded animated GIFs, audio, and a strong narrative make this an excellent example of this form.
Once you’ve got a story you think works, move on to Step #1. If you don’t have a story of your own handy, go on over to The Gutenberg Project to browse through the many copyright-free classic tales available for your use. Use the text there, and then choose photos and audio to “illustrate” and enrich your story.
1. Download Sstory
The “framework” we will be using to make a scrolling, immersive story presentation is EJ Fox’s sStory, which is available for download from Github. On the sStory repository page, scroll down. On the right you will see a button that says “Download ZIP.” Press this button.
(Remember: many photos in this tutorial are annotated! Click the photo for a larger version if you cannot read the annotations).
2. Unzip the folder, and view the contents.
It should look like this:
A note to aspiring data-journalists and programmer-journalists: many people believe that you have to learn to program from scratch in order to do all the fun stuff you see happening with maps, news applications, and the like. While learning how to program is a wonderful skill, you should know that A) you can get very, very far indeed without learning a programming language — but simply by learning how to browse the Global Junkyard Of Code to find “parts” to bolt onto your ideas, which is what you just did when you downloaded that ZIP file and B) that even the Real Professionals do not start from scratch. Most of the impressive projects you see are not written soup-to-nuts by a single programming genius but are instead assembled, curated, and made up of original code and code written by others joined together with great craftsmanship. But, onward.
Let’s browse what we’ve just downloaded. In the folder, you will see a file called index.html. That is what we will spend most of the time working with. But for now, click on the folder called “lib.” It will look like this:
The “index.html” page is the main web page that readers of your story will see. All the files in the folders you see here are, in essence, “helper files” that enrich that one web page. One contains images. The “js” folder contains small programs, called scripts, that enable your web page to do fancy things like sliding scrollers, fading elements in and out, and the like. Styles contains .CSS files. .CSS files determine the look and feel of a web page by telling your browser what the background color of a page is, what fonts are used, and things like that.
3. Click on index.html.
Go back to your folder and click on index.html. It should open in a browser. (If it doesn’t, right-click (Windows) or command-click (Mac) and choose “Open With” and select a browser. I don’t need to tell you not to use Internet Explorer, right? Right.
You’ll see a page that looks like this:
Go ahead and scroll around to see what’s there.
sStory supports a growing number of content types:
- Audio (in the form of Soundcloud embeds)
- Video (in the form of Vimeo embeds)
- Timelines (in the form of Verite timelines)
- Maps (there’s a cool trick that will generate a map for you just by adding an address to the code!)
It also supports a number of content subtypes, like “Photo with Big Text,” “Caption,” and “Pullquote.”
4. Download a programmer’s editor.
If you have one, skip to Step 5.
Our next step is going to be editing that index.html file to fill it with our own story. You can’t do that with Microsoft Word! I recommend using a programmer’s editor, generally called a text editor. Text editors have lots of useful tools for editing code, like built in line numbering, and my favorite, syntax highlighting. You know how your spellchecker underlines words that it thinks aren’t spelled correctly? Syntax highlighting is a little like that — it helps you reduce errors in your code by color-coding different parts of your code. After using one for awhile you will be able to sense errors just by seeing that some things aren’t the right color.
5. Open index.html in your text editor.
Go back to your folder, and right-click or Command-click on index.html and choose Open With. Ask your computer to open index.html with your newly-installed text-editor.
When I open it in my editor, it looks like this:
6. Breathe deeply. Meditate! Do not panic!
If you’re totally over it, skip to Step 7.
OMG THIS LOOKS SCARY WHY ARE YOU EXPOSING ME TO THE SCARY SCARY CODE YOU EVIL EVIL PERSON! WHERE ARE THE TRIGGER WARNINGS?!!?!
Now then. It’s not as scary as it looks. Most code, when you come right down to it, is just a very, very nerdy dialect of English. Take a look again. See how many English words there are in there? If you slow down and take it line by line, you’d be surprised how much of what is here that you understand.
For example, look at lines 33-39. Does the text look familiar to you?
Line 38, which reads:
,title: ‘Making beautiful stories easy’
is the same text that appears over the large first image when you look at index.html in a browser.
In essence, the index.html file is a set of instructions that your browser reads to then assemble and display a web page to a reader. And we can change those instructions!
Step 7: Make your first edit
Now we are going to change the instructions that the browser reads to create the web page.
Go back to Lines 33-39 in your text editor.
We’re going to edit Line 38 to make the web page say something different. It’s tempting to just delete line 38 and write whatever we want, but now is a good time to get into the habit of “commenting out” code when you’re changing something, rather than deleting it straight off.
What’s “commenting out”?
When you write code, you can mark particular lines of what you’ve written as “comments.” The browser (or compiler, depending on what you’re writing) does not read these lines — it just skips to the next un-commented line. Different languages have different ways of noting which lines should not be read by your computer.
In this case, we’re going to start by “commenting out” line 38, by putting two forward slashes in front of it (//), like this:
Now that you’ve done that, copy line 38, without the //, and add a new line right above it. But change the part in between the quotes to say something new, like this:
Now, AND THIS IS IMPORTANT, hit “Save.”
Step 8: View Your Changes
Open index.html again in your browser (you can have the file open in your text editor and the browser at the same time). Now it looks like this:
Magical, no? Magnifique! I love it!
9. Start to add your own elements to the story.
Now that you have the basic idea of how sStory works, you can start adding elements of your own story to the basic framework, just by commenting out the example code and pasting in your own elements. I’m going to start with a map created by the participants of the Walkley’s data visualization workshop. Participants in the workshop pulled together a report about how Twitter handles requests by governments to turn over users’ records. Once we were ready, we split up into teams, and one team created a map in TileMill of the requests. Let’s paste that in instead of the header image of police.
First, copy lines 33 through 40, and paste a copy right above line 33.
Then, comment out the old code.
Then, add the URL of a photo you want to use in your story, right after where it says “photoUrl.” I’m going to use the map image we created in the workshop.
When you’re done, it will look like this:
Notice that your commented code has changed color. It’s “greyed out,” to indicate that it’s not going to be read by the computer. (Different editors have different coloring schemes, but yours will probably make comments a different color.
Now hit Save, and look at index.html in the browser again. Now it looks like this:
Oops. That’s not right!
10. SLAY ALL ERRORS
When you do that, the bottom half of the browser window will now have the console, which will show you the error message. The most critical piece of information: what line of code is causing the error?
Aha! Line 37 is causing the error. Let’s look at it again:
Notice that line 37 doesn’t begin with a comma? Fix that and save, and now you’ll see:
11. Fix those titles
But we probably want to change those titles. Change the titles and subtitles on lines 19 and 20.
And why not add a caption to this map, and get rid of the title that doesn’t fit?
Change the type to ‘photoCaption’ and add a ,caption. You can use HTML in captions — just be sure the whole caption is enclosed in single quotes. (Note that this picture still has the missing comma before photoUrl on line 37. Be sure to fix that.
Save it, and reload it in your browser. Now it looks like this:
The map, originally created in TileMill, was spruced up by workshop participant Mitchell Ward of Rocklily Design.
12. Add some text to your story
I’ll admit, I find working with text in this context a little tedious. I’m sure there’s a better way, but until I find it I’ll show you what I do.
Here’s the hitch: each text segment has to be on one line. You could have 1,000 words and 10 paragraphs, but in your index.html file it’s going to be one enormously long line.
So I’m starting out here:
As I add the text of the story, it turns pink as I pull it into one line. You ‘mark up’ your text with HTML. So, if you have a paragraph, it’s enclosed in “<p></p>” tags. For a basic HTML cheat sheet, look here.
The Single Quote Problem
sStory puts the elements of your story — text, photos, whatever — inside single quotes. So what happens when you use a single quote, like an apostrophe, in the text you want to include? Well, sStory thinks that’s the end of the text you want to use. See how it changes color? Gotta love that syntax highlighting:
You can fix that by “escaping” the character. You do this by putting a backslash right in front of the apostrophe, with no spaces, like this:
That backslash won’t show up in the final product.
13. Comment out the stuff you’re not using.
There’s still quite a bit of example code in your index.html page, putting in stuff that’s not part of your story. Comment out the parts you’re not using.
Putting // in front of each line is a little tedious, though. Your text editor will have a way to let you highlight text and then comment or un-comment it. Poke around until you find it.
Can’t get it quite right? Here’s the raw code I’ve been modifying as I create this tutorial. I’m still working on it a bit — I notice when I comment out photoMulti, I get an error, for example. So I’ve either got to figure out the error…or add a slideshow Scroll to the bottom and click “View raw” to get code to copy-paste.