Matt Gemmell

TOLL is available now!

An action-thriller novel — book 2 in the KESTREL series.

★★★★★ — Amazon

Author Marks

blog & code 5 min read

Four days ago, I published an article entitled Tail wagging, about the backlash against skeuomorphic design. It was well received, gaining about 30,000 reads here and links from The Loop, Marco Arment and Khoi Vinh, amongst others.

I get a great deal of pleasure from reading responses to my articles, most of which are via my Twitter account. I was reading the stream of tweets referencing the article via Topsy recently, as I do for all my pieces, and I was once again fascinated by the extracts and quotes people choose to use.

In the majority of cases, the sections people quote from my articles agree with my own impression of what the important points were. I’d love to attribute this to careful writing and well-formed arguments, but of course it’s more due to the reader paying attention.

In some cases, though, people choose to refer to articles (and thus, in a sense, summarise them) using what I feel are either secondary points, or even actual mischaracterisations or misinterpretations of what I’ve said. The fault for that will be mine in some cases, and in others it’ll be the reader’s.

I had a spirited discussion on Twitter earlier today about a vague idea for offering some extra insight regarding my own view of an article’s salient points.

There were a few standard suggestions, which I’d already dismissed as not quite appropriate. Emphasis, for example, is more of a linguistic tool (to indicate or be analogous to verbal emphasis) than something to be used at the logical level. I also think that emphasis is ugly and diluted when used for more than a single clause or so.

The next suggestion (and probably most popular overall) was pull-quotes. I’ve used those perhaps twice in total on this blog before, and each time I felt self-conscious about it. Pull-quotes can make you seem arrogant, in my opinion. There’s something crass about them.

Since this discussion took place on the internet, a few people even deigned to give me a high school writing lesson, saying that no additional means of highlighting passages should be needed if I just make my point properly. Thanks for that.

Abstracts were mentioned (I think that arguments should be allowed to build; I’m not writing academic papers), as were sub-headings (similar objection to abstracts), and unacceptably ugly inline styling like boldface or underlining.

Things got a bit more interesting when Branch was mentioned, which has the sort of neon-highlighter-pen concept I’d been thinking of - you can see examples here, though again I don’t like the underline; only the hover appearance. That implementation is reasonably close to what I’m after.

No matter how carefully written a piece may be, the reader is an unknown factor. Different people will interpret your words differently, and it’s not possible to completely eliminate that. Perhaps that’s even a positive state of affairs.

In any case, everyone will have different “take-home points” from a piece of writing. As I see after publishing each piece, everyone’s highlights (or summaries, or key points) are unique. The author of a piece has of course conveyed their position in the piece itself, but (except for perhaps an initial tweet, or the meta description contents of the page) we’re not often in the position of listing our own highlights.

I think that’s a shame, because there can be value in getting a sense of what the author of a piece feels is the main thrust of their own argument, or a sense of what they feel might be notable or quotable.

Accordingly, I’ve implemented a system to do that on this blog, which I hope to use in future. I’m also providing the relevant code so you reuse it yourself if you wish. I call these annotations Author Marks.

My design criteria were contradictory:

  1. Don’t be visually intrusive, or imply arrogance.
  2. Replicate highlighter-pens on paper.

As I thought about it a little more, I realised that Author Marks are somewhat like extras on a DVD; a little bit of additional content, which you must choose to view, giving some insight into the piece from the author’s perspective.

For simplicity, I decided to make use of the HTML5 mark tag (with the author-mark CSS class applied) to indicate those segments. This has the advantages of being semantically valid, portable, and readily accessible to user-specified stylesheets.

<mark class="author-mark">An important point to note</mark>.

Highlighting of marks is off by default, but I’ve made a simple JavaScript which you, dear reader, can use to enable highlighting if you want to. The appropriate activation links are in the footer of each article (and only on articles which actually have author marks). When active, the activation links look like this:

Author Marks toggle

For the sake of demonstration I’ve also added a live activation link here:

I’ve added some gratuitous marks in this article’s text so you can readily test the functionality. For example, this phrase has been marked. In actual usage, I’d try to limit the number of marks to a handful per article.

For those reading this in a feed reader, or with JavaScript disabled, here’s a screenshot of how it looks.

Author Marks

You can find the JavaScript in this github repository, complete with instructions for use.

I’ve gone back and added some marks to my Tail wagging piece as a sort of test run.

It’s my hope that this can serve as a way for me to provide a hint about my own sense of a piece’s key points, and highlight anything I think is particularly pithy. You’ll be free to either be complicit, or just amused at my own vanity or (in your opinion) misguidedness.

I’m very interested in further discussion on this topic - but do feel free to wilfully mischaracterise this article on Twitter instead.