How to Compose an Annotation-based Tweet

Annotation is one way to remix the web, Twitter is another. The two approaches can play nicely together but, to make best use of the combination, it helps to understand what happens when you tweet a Hypothesis direct link. You start by capturing the link as shown here:

This is the template for a direct link:

https://hyp.is/a/{AnnotationId}[/{url}]

Here’s an example that fills the slots in the template:

https://hyp.is/eVUuThRlEemoznciD_8Jgw/web.hypothes.is/blog/collaborative-resource-curation/

As in other systems, like Trello, the part that comes after the {AnnotationId} is optional. It describes the link for the benefit of a person who sees it, but the software that resolves the link doesn’t use that description, so you can simplify the example to just this:

https://hyp.is/eVUuThRlEemoznciD_8Jgw

When you click the link, the service running at https://hyp.is (which we call bouncer) figures out if you’re running the Hypothesis extension or not, and delivers the annotation client accordingly. If you are running the extension, the browser loads the page, activates the annotation client, and scrolls to the annotation’s highlighted target. Otherwise bouncer sends you through the Hypothesis proxy which loads the page, injects the annotation client, and then does the same thing: activates the annotation client, and scrolls to the annotation’s highlighted target. If you include a direct link in a web page, or in an email or chat message, this screencast shows the experience your link will deliver.

When you tweet the link, you can deliver a more layered experience. You may be familiar with how WordPress interacts with Twitter. When you tweet a WordPress link, Twitter looks for ways to contextualize the link. By default it will present the first image in the post, if there is one, and an introductory snippet of text. You can be more intentional, though, by telling WordPress to feature the image and the snippet that you think will best represent the blog post to your Twitter audience.

Hypothesis direct links also have a default presentation on Twitter, though it varies according to the type and composition of the annotation whose link you are tweeting. If you want to experiment with the variations, you can use Twitter’s Card validator to preview how your direct link will look.

There are two slots your annotation can fill on the Twitter card. I think of them as the headline and the subhead. The rules of this game are:

1. If your annotation targets a selection, the card’s headline will be that selection, truncated to fit the available space.

2. If your annotation is a page note, there is no selection, The annotation refers to the whole document. In that case, the card’s headline reports the document’s domain.

3. If your annotation includes a comment, the card’s subhead will be that comment, again truncated to fit the available space.

4. If your annotation does not include a comment, the card’s subhead will instead say: Follow this link to see the annotation in context.

Here is a preview of a link to a page note that has a comment. Because the annotation is a page note, the card can’t use a selection as the card’s headline, so it uses the domain targeted by the annotation. But the annotation does have a comment, so that becomes the card’s subhead.

Here is a preview of a link to an annotation that does target a selection. The selection becomes the card’s headline. If the annotation included a comment, that would become the card’s subhead. Since it didn’t, the subhead falls back to Follow this link to see the annotation in context.

The boilerplate text shown in both of these previews (“The card for your website will look a little something like this!”) represents the comment that you would write in the tweet to contextualize the link. What should that comment be?

If the linked annotation is itself a comment on the selection it targets, you can use the tweet to say something else about that selection. Or you can use it to say something about a comment that you made in the annotation. There’s no right answer! You can mix these layers as needed, and they can influence one another. If you’re annotating with the intention to tweet your annotation, and you know your annotation’s target selection will be the headline of the Twitter card, you can choose it and size it accordingly. Likewise, when you write the annotation’s comment, you can imagine the comment as the card’s subhead, and again choose and size it accordingly.

When you are the author of the annotation and the tweet, you gain an extra degree of freedom. Now you also control a higher-level headline: the comment you write in the tweet. The annotation’s selection, which is the card’s headline, gets demoted to the tweet’s subhead, and the annotation’s comment, which is the card’s subhead, gets demoted to the tweet’s intro. If you’re annotating with the intention to tweet, you can bear that in mind as you choose your selection and write your comment.

If, on the other hand, you are writing a tweet that links to an annotation someone else wrote, then you don’t get to make those choices. In this example, Chris Aldrich has annotated a blog post with a comment.

I wanted to amplify his comment, so I used my comment on the Twitter card to do that.

There is a subtle thing happening here. The annotation looks like it targets a selection, but in fact it doesn’t, it’s a page note, which is why the headline on the Twitter card says Hypothesis annotation for web.hypothes.is. If Chris Aldrich’s annotation had instead targeted a selection in the blog post, that selection would be the card’s headline, and I’d want to consider whether it worked as a headline for the card I planned to tweet.

Why does the selection (“No software had to be written…”) appear in the screenshot? Because that’s the selection I targeted with another annotation I made on the same blog post. My selection isn’t the target of Chris Aldrich’s annotation, it just happens to be visible on the same page when the Hypothesis page-note tab is active. I’d like to say that I planned that, but I didn’t, it was a happy accident.

Annotation alone is a powerful way to remix the web. When you add Twitter into the mix, possibilities multiply. Outcomes can be unpredictable, and you don’t want to make a mistake in public. But if you use Twitter’s previewer to check your annotation links, you can safely explore the interplay between these two complementary forms of social media.