Designing annotations to fit the narrative

Last month the Storytelling Studio, in collaboration with Vox.com editorial and video teams, took our audience on a treasure hunt. This is the story of the annotated poem, which is central to the narrative.

As soon as we sat down with Vox.com reporters Zachary Crockett and Estelle Caswell, it became clear that Forrest Fenn’s poem played a critical role in not just their experience, but in the theories and journeys of all treasure seekers that Fenn has captivated since burying the treasure in 2010.

Fenn’s poem is the map to his treasure. It isn’t a typical treasure map with marked paths or an “x marks the spot,” but a 24-line poem containing nine clues to where the treasure is hidden. Any theory worth investigating is based on clues mentioned in this poem.

While discussions about design, layout, and user interaction wouldn’t happen for another few weeks, we came out of that first meeting with a basic understanding of the story we wanted to bring to life. And one thing I recognized immediately was that this poem would be mentioned early and referenced often.

Start with inspiration

When starting any project, we typically complete some kind of competitive analysis. So I did a bit of looking around to see how others have handled annotations on the web. I started with Vox’s annotated version of Trump’s Inauguration speech, which some of my teammates worked on with the Vox.com editorial staff, and “Donald Trump’s Inaugural Speech, Annotated,” by the New York Times.

While Vox.com places the annotations under the related paragraph at all breakpoints, I liked how NYT piece floated the annotations to the right of the speech content on wider breakpoints, only moving them underneath when necessary. While both versions adequately accomplish the task at hand, the NYT version resonated with me because the style reminded me of annotations that I would write. Notes scribbled in the margins of articles or books — this feels real to me. This is how I work, and the way that I’d annotate the poem if I were going on this journey.

Experiment and iterate

I was lucky enough to be given creative freedom to figure out how to best display these poem annotations, so I tried a few things.

I first tried floating the annotations to the right of the poem and horizontally aligning them with the matching clue (as closely as possible).

After writing a bit of collision detection for the annotations to prevent them from overlapping, I found that this approach technically “worked” but looked rather messy and didn’t give off the same polished feel that the rest of the assets in the piece do.

My next thought was to space the annotations out evenly in the right column. They’d no longer be aligned with the corresponding clues, but they’d get a bit more breathing room.

This was a good start, but in giving the annotations this much-needed space, the element of proximity that had been tying the annotations to the clues had now been erased. I needed to reestablish the link between the annotations and the clues. This is where I drew most heavily on inspiration from the NYT piece, both in visual appearance and in technical execution.

Technical implementation, a step-by-step overview

While I can’t speak to the exact technical implementation of the annotations in the NYT piece, I do know a few things about how it works. It first creates a Scalable Vector Graphic (SVG) set to the same width and height as the content it’s annotating — essentially creating a blank canvas for the annotations to be drawn on — and sets it behind this content. Then, using SVG Path elements, draws lines connecting the highlighted sections to the annotations.

I also created an SVG that scales to be the same height and width as the content (the poem), but instead placed it on top (rather than under) the content. For the sake of allowing the user to highlight the text more easily, I’d also place the SVG behind the content if I were to ever create something like this again.

Adding the lines

After creating the SVG, sizing it, and aligning it with the top of the poem, I needed to create the starting and ending points or each line.

The code below demonstrates how to create the point shown above corresponding to the first clue.

var pos = $("#clue0").position();
d3.select('#poem-lines').append('circle')
  .attr('id', 'c'+i)
  .attr('cx', pos.left + $(this).width() + 15)
  .attr('cy', pos.top - 13)
  .attr('r', 3)
  .attr('fill', 'red');

var lineFunction = d3.svg.line()
                     .x(function(d) { return d.x; })
                     .y(function(d) { return d.y; });

# Select each of the poem annotations
$.each($('#poem-annotations div'), function(i){

  # Select the x and y positions of the corresponding clue and annotation points
  var lineData = [ 
        { "x": d3.select('#c'+i).attr('cx'), "y": d3.select('#c'+i).attr('cy')},
        { "x": d3.select('#a'+i).attr('cx'), "y": d3.select('#a'+i).attr('cy')}
      ];

  # Append the corresponding path to the svg and call
  # the line function that will draw the line
  d3.select('#poem-lines').append("path")
    .attr("d", lineFunction(lineData))
    .attr("stroke-width", 2)
    .attr("stroke", "blue")
    .attr("fill", "none");
});

The result looked like this:

Styling the lines

The points were connected now, but the lines were very sharp and didn’t have the softer, hand-drawn feel to them that I had envisioned.

While I’m sure there are multiple ways to do this, I chose to add extra points to the lines themselves, one 20px to the right of the leftmost point and one 20px to the left of the point on the farthest right to create the additional sections I needed.

# The two middle items, lineData[1] and lineData[2] are 
# the two points that we are adding to the line
var lineData = [ 
      { "x": d3.select('#c'+i).attr('cx'), "y": d3.select('#c'+i).attr('cy')},
      { "x": parseInt(d3.select('#c'+i).attr('cx')) + 20, "y": d3.select('#c'+i).attr('cy')},
      { "x": parseInt(d3.select('#a'+i).attr('cx')) - 20, "y": d3.select('#a'+i).attr('cy')},
      { "x": d3.select('#a'+i).attr('cx'), "y": d3.select('#a'+i).attr('cy')}
    ];

The code above produces lines looking like this:

var lineFunction = d3.svg.line()
                     .x(function(d) { return d.x; })
                     .y(function(d) { return d.y; })
                     .interpolate("basis");

Adding the arrows

The lines were looking better now, but they still felt a bit unfinished. I toyed with the idea of using circles on both ends of the line, which probably would have looked alright, but decided to give the arrows a shot since they most closely imitate the annotations style that I’d draw by hand.

$.each($('.clue'), function(i){
  var pos = $(this).position();

  # Line data used to create the leftward facing arrows
  # pointing to each highlighted clue
  var lineData = [ 
        { "x": pos.left + $(this).width() + 23, "y": pos.top - 18},
        { "x": pos.left + $(this).width() + 13, "y": pos.top - 13},
        { "x": pos.left + $(this).width() + 23, "y": pos.top - 8}
      ];

  d3.select('#poem-lines').append("path")
    .attr("d", lineFunction(lineData))
    .attr("stroke-width", 2)
    .attr("fill", "none");
});

The end result becoming this:

By scaling and redrawing the annotations on resize, this design works at various breakpoints. It eventually switches to a different view around 600px wide.

Swapping to footnotes

While I initially tried putting the annotations under each stanza, similar to how the Vox.com annotations format adds annotations underneath each corresponding paragraph, this broke the poem up too much and created a rather disjointed reading experience. Instead, I opted to put them all below using footnotes to connect the clues to the annotations.

In the on-platform version, the clues and annotations are tappable on smaller screens. This was actually a suggestion that came out of one of our user testing sessions. Since the poem and annotations no longer fit within one frame, the user felt that it would be helpful to be able to navigate quickly between them. Adding this feature was our response to that suggestion.

Tying the poem into the narrative

Given the critical role the poem plays in Zack and Estelle’s journey, it was important for us to clearly show how directly tied many of Zack and Estelle’s actions were to the clues in the poem.

Our solution was to borrow from the design language we established in the poem and use the same style to highlight these clues interspersed throughout the narrative. This immediately makes clear that these clues were mentioned earlier and prevents the user from having to guess or scroll back up to the poem for reference.