Tuesday, August 13, 2013

Academia and End Notes

After you have finished this, be sure to read the Remix (update) published in November 2013.

Years ago - almost too long ago to remember - I was a student in the Philosophy program at a small, private university in the US, and one of the requirements for completing a degree in the program was the completion of a thesis of some length. Although there were arguments on both sides of the footnote vs endnote debate1, the program did not stipulate whether the author was to use footnotes or end notes, and since in those days we didn't have powerful word processing software that simplified footnotes, most people in the program avoided footnotes.

Fast forward to today, and as I write this blog, I find myself wondering about this topic again. The largest reason is because I still like to reference the work of others. I've been around enough to recognize that there are areas in which I am an expert but also areas in which I have to draw on the work and contributions of others, and I like to give them the proper respect as much as I appreciate it when they give me credit for work I've done.

Being a big proponent of semantic HTML2, as I started thinking about how to best represent notes in semantic markup, it became relatively clear that end notes were the best choice. Of course that still leaves me with the big problem of people having to jump around in the document to find the additional detail they seek. That was why I wrote the first version of the Notes library for cathmhaol.com.

Unfortunately, that version uses the title attribute of the span that serves as the reference for the note, which means it's not accessible. Also, I didn't really like how the note looked when it was displayed - with the layout just governed by the browser. Since I had two problems, and no real solution, I started looking around and discovered that although the design could easily be addressed, there wasn't much agreement regarding how to best make notes (and by extension research) accessible.

After consultation with a colleague who is much, much more familiar with topics surrounding accessibility, here's the solution I can up with - and one that I believe is workable with a minimal amount of effort.

First, we make the note reference (we're going to go with the typical approach of using a number) superscript - we're using superscript because it's widely recognized among readers as indicating a note. Next, we're going to put identifiers on the note so that we know which group of end notes to link it too. Finally, because the SUP tag is read inline as text by screen readers, we're going to add an ARIA attribute - aria-describedby3 - to identify that it's not just content. What we have is something like the example below.

...we're going to add an ARIA attribute - aria-describedby<sup aria-describedby="note-info" class="tooltip endnote" id="note-indicator-3">3</sup> - to identify that it's not just content.

Next, we add our end notes as an ordered list, but we're going to use the header of the notes section as the note-info element so that the aria-describedby attribute works, and inside the list items, we're going to use a note-indicator-n as the id so that the link back to the note reference - using the aria-labelledby attribute4 - works. This gives us code something like the example below.

<section>
  <header id="note-info">Notes - links open in a new window</header>
  <ol id="tooltip-notes">
    <li id="note-indicator-1"><a href="http://scottberkun.com/2007/footnotes-vs-endnotes-the-debate/" target="_blank">Footnotes vs Endnotes</a></li>
    <li id="note-indicator-2">Semantic HTML....</li>
    <li id="note-indicator-3"><a href="https://developer.mozilla.org/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute" target="_blank">Using the aria-describedby attribute</a></li>
    ...
  </ol>
</section>

Finally, we're going to add the JavaScript library, which will transform our code even more, adding the style rules for the CSS arrow and a data-* attribute5 that will use it - all by specifying the list of notes and the data-* attribute to use.

<script src="http://js.cathmhaol.com/cjl-notes.js"></script>
<script>
var n = new Cathmhaol.Notes(document.getElementById("note-endnotes"), "sup", "tooltip endnote", "data-tip");
</script>

If you've followed along so far, the heavy lifting is done. You can, of course, tweak the style rules that display the CSS arrow - and you can change the attribute used for setting the content of the tip - but the colors used should be compatible with a majority of sites and offer enough contrast to not be onerous.




Notes - links open in a new window
  1. Footnotes vs Endnotes
  2. Semantic HTML is the use of HTML markup to reinforce the semantics, or meaning, of the information in webpages rather than merely to define its presentation or look. Learn more on wikipedia.
  3. Using the aria-describedby attribute
  4. Using the aria-labelledby attribute
  5. HTML5 data-* attributes allow you to embed data into your markup in a way that does not affect layout or presentation. Get a brief introduction on John Resig's blog.

No comments:

Post a Comment