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.

This tutorial was inspired by my Australian journalist friends, who came to a workshop I taught hosted by The Walkley 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. We didn’t quite get done, so these step-by-step instructions are what you need to know if you want to try it out.


0. Ask yourself: is this the right story for this format?  

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:

  • Text
  • Photos
  • 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.

There are many good free text editors.  For Windows, you may want to try Notepad++.  For the Mac, there’s TextWrangler.

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.


Breathe!  Breathe.


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 33 - 39


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.

Line 33 - 39


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” in your text editor.

Step 8: View Your Changes

Open index.html again in your browser and reload the page (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!


If you are using the Google Chrome browser (and I recommend you do), there are built in tools for coders that help you detect & fix errors.  In Chrome, you can find this by clicking on View > Developer > Javascript Console.

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.  One thing to know about error messages:  Sometimes the error is on Line 37, but a lot of time I notice that the error is actually either on Line 37, or the line directly before it. Let’s look at it again:



Notice that line 36 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 36.  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.

14. Now add other stuff.

You can add many different kinds of elements to your story — text, photos, video, audio, in exactly the same way that we added a photo — you just add the URL in the right place.

  Okay, but how do I get this onto the web?  

Right now, your immersive story is sitting on your desktop where only you can see it.  If you want to get it onto the web, you’re going to need access to a web server.  There are many web hosts out there.  I’ve heard people say good things about BlueHost and DreamHost, each of whom have plans that cost less than $10 USD a month.  I use MediaTemple, which is a little more pricey but has a few features I need & I’ve been happy with the support I get when something goes wrong.   Now that you’re doing these kind of experiments, it’s time for you to get your own little pied a pixel on the web for your stuff to live so others can see it & share it.

Once you have some hosting space, you can upload your files to your hosting account.  Some web hosts feature in-browser upload tools and others require you to use SFTP (Secure File Transfer Protocol), an old-school but devastatingly efficient way of getting a whole mess of bits from hither to yon.

Once it’s up there, what do you type into your web browser to show it to people?  What’s the link?

Well, that depends on whether or not you bought a domain name.  Your web hosting account will have something called an IP address, a long string of numbers.  Every device that connects to the internet has an IP address, a unique locator.  For example, the IP address of the web server hosting the web page you are looking at is:

Even if you don’t have a domain name (yet, but you should! You’re fabulous and you should hand it out on cards and things), you can usually get instructions from your web host on how to type in something like:

Once you get a domain name, it’ll be more like   /myproject is a folder, and if there’s a file in there called Index.html, your browser will load that one.

This isn’t working but I’m not sure what I’m doing wrong.

OK, first, take a deep breath.  Everybody gets stuck, even the pros, all the time. [See also: Making Friends With The Stuck.]

If you want help from others on fixing your code, you have to have a way of showing it to them.  The most efficient way for you to do that for small files like the index.html file you’re working with is to use Gists.  Gists are like scrap paper, only for code.  You just copy and paste your code that’s not working into the web browser, and then you can share the link so people can see what’s up.  Go and get a free account at Github, and you’ll notice the word “Gist” in the top menu.  Click on that and you’ll be able to make as many Gists as you like.


Leave a Reply

Your email address will not be published. Required fields are marked *