Andrew Bray - Closeread: bringing Scrollytelling to Quarto

My name is Andrew Bray and I teach classes in statistics and data science at UC Berkeley and I want to start off this talk with a story going back two years to March of 2022. So the semester is coming to a close. I have a final that I have to give in a couple weeks and so what do I do? I protrastinate writing my final because I really it's really hard to write finals so I do everything I can to not write a final and I do my favorite form of procrastination which is going on my laptop going to NewYorkTimes.com and clicking through articles and pretending that I'm edifying myself on procrastinating and while doing that I came across this article so it's called a poem and a painting about the suffering that hides in plain sight by Eliza Gabbert.

I want to read it to you. I've been reading this short wry poem about suffering for more than 20 years. How nice that it tells you in the first two words what it's about. No matter how familiar a poem is rereading it always gives me a sense of first encounter as though I've gone back to sleep and re-entered the dream through a different door. And the article goes on this is a form of web design called scrollytelling where you have a narrative that's scrolling down the page as you scroll but that scrolling behavior is modifying what you're looking at. So it could be panning across images, it could be highlighting text, it could be zooming into text, could be playing video and you know as I read to the very bottom of this I looked up at the clock 25 minutes have passed. This is a very long article and I was just realizing what just happened. I don't consider myself a huge like poetry guy and yet I just spent 25 minutes reading about poem by W.H. Auden and found it fascinating and I realized that it really was the medium that was so effective at engaging my interest.

really was the medium that was so effective at engaging my interest.

So you know I think about as a teacher how can I provide materials that my students will engage with when they're reading it and I thought man if I could engage my students just a fraction of the way that Eliza Gabbert was able to engage me this is gonna be really powerful. So I start started to think how can I take Quarto and create a scrollytelling story like this and two years ago I came to PositConf I'd kind of drum something up very hacky I showed it to Mina and she's like that's nice you should talk to James. So this is James Goldie he's a data journalist and he lives in Melbourne Australia and turns out he had been thinking about the exact same thing not from a teacher's perspective but from a data journalist perspective and he'd also drum together kind of his first try at Quarto scrollytelling. So this started off a two-year collaboration that has resulted in a new Quarto custom format that we're pleased to share with you called CloseRead.

So CloseRead it's a Quarto extension that enables scrollytelling to well can do lots of things but today I'm going to show you three documents in which we'll study text, we'll study images, we'll study code all to make a stronger more focused narrative. All right so we're gonna start off with studying text but actually before I get there I just want to say that in the course of this talk I want to give you a sense of how easy it can be to author one of these things in Quarto but I also want to see if we can drum up like what is it about scrollytelling that makes it so engaging what exactly is it as a storytelling medium.

Quarto syntax basics

All right I'm also just gonna some jargon here that I might actually not need to cover now because it's come up in the previous talks. One is this notion of a fence div so if you have a block of content in your Quarto doc you can wrap it in triple colons and then inside curly braces give it things like identifiers, classes, and attributes. So you can encode a lot of information in the different components of your document. If you have a block of content in your document you'd use the fence div. If you have just a part of say a paragraph you'd instead use the bracketed span. So very similar syntax you can pass the same amount of information but you're gonna use these square brackets instead of the triple colons. All right so that's kind of gonna be the the syntax that we'll leverage here in our extension.

Studying text: recreating the New York Times article

All right so for our first document I'm actually gonna try to recreate just a bit start towards recreating that New York Times article. It should be said that that article I got in touch with Eliza Gabbard. She was really gracious telling me about the process. It's impressive what they're doing at the Times. It took five people several months to produce that article and it's a masterpiece. One of those people was Eliza Gabbard. Four of them were web designers and if you look through the HTML it's really boutique to exactly what they're doing here. So the goal is to kind of allow somebody who doesn't have a team of web designers to do something like that.

All right so here is the title and the first couple lines of Eliza Gabbard's piece and here it's just as a straight HTML file. If I were to render it I would see kind of a familiar sort of format. In order to get towards the scrollytelling the first thing that I'm going to do is actually do something that's purely aesthetic. So I'm just gonna add some CSS that will bring in some identifiable fonts and I'm actually going to do something that has been in Quarto for as long as it's been around. I just learned that it exists. It's called the line block. So if you have text that you want to preserve the formatting into your rendered document you can precede on the left side by a pipe and then a space. We'll create what's called a line block and oops there it is and you'll get that poem at the bottom looking like a poem and then now we have this New York Times fonts or similar fonts.

All right but to really make this a scrollytelling story we're gonna need to do a couple things. We're gonna start off by changing the format there on line 2 to be close read HTML and then we're going to wrap all of our content in a fence div and give it the class CR section. What that'll do is give us this identifiable two column layout where you have a narrative block and then a block on the right where our content will land. If we go ahead and scroll down that you'll realize okay so it's separated out each of those paragraphs that's cool but right now the poem is actually showing up there in the narrative side. So that's the default kind of in a CR section everything gets tossed into the sidebar. What we need to do next is be clear that it's this poem that we really want to study. So the way that we flag it as such is we wrap it in a fence div and we give it an ID and we prefix that ID with CR hyphen. So that's the first step and the second step is that we provide a reference to it in the paragraph where we'd like it to appear when that paragraph hits the middle of the viewport. So in terms of our own lingo around this we call the the poem now is called a sticky because we think about it like a sticky note that we're just gonna stay in the middle of the screen as you're scrolling the narrative and then we call the reference to a trigger because it's gonna trigger different effects.

Alright so with that in place we can go ahead and watch it and there we go as that first trigger comes into view it's gonna make the poem appear. So that's we're getting kind of looking somewhat convincing but they have lots of effects that they're triggering not just the poem appearing. One thing that they did is they were highlighting text and they were zooming into it. So we can do that. First thing that we're going to need to do is specify there with a bracketed span where we want to highlight and zoom. So I'm gonna call that the CR suffering and then we need to provide a trigger for it. And here we're appending a little bit of extra information to our trigger saying when this one triggers highlight and zoom HLZ that span CR suffering. And once we've done that the first block will make it appear. Now the second block will highlight and kind of center it in the viewport.

Alright so just to recap what did we learn to write a close read story you're gonna create the close read section step one. Step two is flag content as stickies, sticky notes that will appear and stick around as you're scrolling down. And then identify blocks to serve as triggers of different things appearing or having focus effects. Alright so you know as I'm trying to think okay that was close read our implementation what do we learn about scrollytelling? Well we found ourselves drawn to Quarto's built-in cross-referencing syntax and we've realized that scrollytelling it's really using kind of spatial cross-referencing. It's replacing in a static document where you would say like see figure five now it's just figure five is there. So you don't need that it's it's the the spatial kind of concordance between the sticky and the trigger that's doing the work and kind of reducing that cognitive load for your reader which I think is part of its power.

Studying images: Napoleon's march

Alright so that was text let's go ahead and study some images. So this is maybe one of the most famous images in the history of data visualization Napoleon's march on Moscow. This is as it appears in Edward Tufte's The Visual Display of Quantitative Information. This is page 40 and you know he does a terrific job I should say speaking of cross-references of being sure that the figure that he is describing is always on the same two page spread as where he's describing it. You will not need to turn a page to see the figure that he's discussing but let's see if we can kind of make this even easier to read by using a close read.

So here's a start of this document I've already created as a close read document and we can see Edward Tufte's text is in there just the start of it as well as an image for Menard's map. If we look at that it just stacks it kind of like a normal HTML article. To create the close read section we need to open up that div that happens right there. The second step is that we need to identify the sticky that's going to be the map and the third thing is we need to make a trigger. Let's just make the first one trigger it. So that'll go ahead and that first paragraph since it shows up in the middle of the viewport Menard's map is just right there. But nothing's really changing right now and his text actually is really descriptive about where you should be looking in this map to see different things.

So let's return to his text. The second line in his paragraph where he's describing it he's saying something like beginning at the left at the German-Polish border at the Neman River you see something. So we can just go ahead and say well trigger there some panning behavior so we want to pan a little bit to the left a little bit down and I'd like to zoom in a bit scaling the image. When I do that when that paragraph comes into view now we can see actually you can see the Neman River you can see that that that national border and see the thick tan flowline showing the size of the Grand Army. All right so the next paragraph is just describing what that band says but the the following one says something like in September the army reaches Moscow. So let's bring Moscow into view just by panning and scaling again right there and now when we hit that third narrative block I'm sorry fourth narrative block it'll pan over there to Moscow.

So if you'd like to see a more extended version of this you can go on our website which I'll show at the very end that does plays a little bit more with this graphic. How about just to recap what we learned here we're still gonna be using this focusing behavior but now we're gonna be using panning and scaling to zoom around our images and I've done this in the context of images but actually this behavior panning and scaling works for any type of sticky. We could actually pan and scale that poem if we wanted to or any text or any code it's a really general behavior here. There's quite a few focus effects right now there's the panning there's the scaling we saw HLZ in the poem that was highlighted in zoom or you can do them individually highlighting and zooming.

Okay so just before we leave this one behind I just want to point out that read this paragraph it says or I guess it's a sentence beginning at left on the Polish-Russian border near the Neman River. All of that is all just telling you where you should be looking here so you know now that we have it right alongside it's not really necessary superfluous and I think what this is flagged for me in putting this together is when you're writing text for scrollytelling it's just categorically different than static text because static text has a lot of where you should be looking not what you're looking at. So what this has taught me is that scrollytelling allows the reader to focus on the what instead of the where and this is just a good flag when you might want to write a scrollytelling article is if you look back on your writing and it's all just telling you to look at on the third sentence of the fourth paragraph on the sixth page maybe just show them right next to that exactly where you're referring to.

scrollytelling allows the reader to focus on the what instead of the where

Studying code and interactive graphics

All right finally we're going to look at a little bit of code. So we're going to start here with a pretty familiar pretty simple example. We have some R code in this case a dplyr pipeline and we want to walk our readers through what it's doing. So we have the familiar elements, we have the CR section being open, we have the now whole code cell is being flagged as a sticky, I'm calling that CR dplyr, and then we are referring to it with a trigger. If we go ahead and take a look at what that produces you just have the side-by-side layout and we have the code and the output. To walk a viewer through it this is a classic case for code highlighting. So to do that say in this second narrative block I could say I'd like to highlight lines one and two right there and now when I scroll down to that it'll just highlight the loading of the packages. If we'd like to highlight more than just one line at a time we can highlight a range so I say that we'd like to highlight lines four through eight and then when we get down to that third paragraph we'll see the actual dplyr pipeline.

All right so what we saw here is some syntax around attribute some focus of X that we can use highlighting line numbers, highlighting ranges of line numbers, you can also highlight spans, but in fact this exact syntax we could have used over in the text. So in the CloseRead custom format pretty much anything, almost anything you can do for text you can do for code, and anything you can do for code you can do for text. There's one small exception.

So this is actually kind of a not that exciting of an example my third example about telling you about code. The example that I really want to tell you about is not showing code but thinking about your users behavior in your document as data that you can use to modify the graphics that they're looking at. Okay so let me just show you an example to explain what I mean by this. This is a little CloseRead the objective of which is just to draw a globe that shows where James and I live. So we can see we are opening the section something different here we're specifying we don't want the sidebar layout I want actually the the narrative to scroll down the middle so I'm switching it to overlay center. I have a little trigger here saying that I would want to see the globe when I describe where I live, and then here's the code that's going to generate the globe. So in this case I'm using OJS in the plot package. This first code cell is loading in some data. The second code cell is actually creating this globe using observable plots package. And I'm not terribly familiar with this package James definitely is so James put this together. And if you scroll down to the very bottom you see there's a little specification of the projection that just says where how do you want the globe to be rotated. And I wanted it rotated at longitude of 122 so that when I go ahead and render it we get to see where I live in Berkeley, California.

But I could have done this with a static graphics library. OJS is interactive graphics so we can do better than this but we're gonna need one more piece of information. We need to be tracking where your user is scrolling. So what I've done here is I've extended these narrative blocks. My collaborator James lives very very far away. I want each of them to trigger some behavior on the globe and I'm wrapping it in a div called progress block. Now what that's going to do is make available to our code cells, our OJS code cells, an OJS variable called CR progress block. So now I'm just going to show you what this looks like, what you're going to see in the upper right hand corner now. It's the same document pretty much but we're actually going to just see the value of CR progress block. See it starts near zero as you scroll down it starts approaching one. Alright so that's something we can use. We're actually restoring the data on what our user is doing. So the way we're going to use it is we're going to go ahead and add a little bit more code in here that's modifying on line 31 that 0 to 1 variable and mapping it to longitudes 180 to negative 160 and then we're going to swap out that static hard-coded 122 longitude and replace it with this dynamic one. Let's see what happens. So we learned that James lives very very far away.

So this is a fairly simple example just rotating a globe. It's kind of a proof of concept but there are all sorts of very very complex interactive graphics that using scroll retelling you can give your user really easy control over what they're seeing in that graphic. Alright so just to recap here you can span narrative blocks with progress blocks and then you have this CR progress block OGS variable. There are actually four others that we make available as well and we also saw that there are choices in terms of layout. So I guess what did I learn from this last section? Well I learned that scroll retelling is a great match for interactive graphics and I think there's lots of potential for you know interactive graphics storytelling in a teaching context and in a data journalism context.

Use cases and closing

So different ways that you could think about using CloseRead. I would guess James is thinking about you know having a CloseRead section in one of his data journalism articles. As a teacher I'm thinking about okay if I have a particularly tricky concept and I can't be in front of my students to explain it maybe I'll prepare a CloseRead article. I'm also thinking about maybe my students as they're working on their projects and data analysis asking them to walk their reader through an analysis by writing a CloseRead project. I'm also imagining folks that are working in industry trying to communicate a central insight of an analysis to company decision makers. So I've seen lots of amazing dashboards that today at this conference and I see so many options, so much richness, so much complexity that's wonderful but also maybe for a new user would benefit from a more guided curated tour through something like a CloseRead article. And finally you can use it as a guide to software that you produce. So with that I just direct you to our document site closeread.netlify.app where you can learn all about it. Thanks very much.