annotation
This article is a stub. You can help the IndieWeb wiki by expanding it.
Annotations are comments (including marginalia), highlights or any other interactions that add to (part of) a post, typically added by individuals other than the author.
How to markup
For how to markup annotations in general, see the individual how to markup sections for what you are looking to markup:
See responses for more types of annotations and details therein.
Use Cases
- See: annotation-use-cases
Opinions
Opinions about "annotation" (the process/action).
Just a means to an end
, https://twitter.com/mrgunn/status/721843419786510336.To me, annotation is just a means to an end, so talking about promoting annotation is mistaken. Promote the end *via* annotation. #force2016
Silo Examples
- News Genius (AKA Genius, RapGenius)
- Amazon allows the sharing of notes and highlights from it's Kindle platform online. Example: recent activity
- Hypothes.is
- Scrible, allows for annotation as well as bookmarking and tagging
- Fermat's Library has a feature called Margins which allows users to upload .pdf articles to annotate and share with others online. It's primarily geared toward the education space.
- Goodreads
- On 2016-08-10 Goodreads enabled the ability to sync one's account with their Amazon Kindle account to port over highlights and annotations from Kindle books to the GoodReads platform and share them with one's followers. (GoodReads is a subsidiary of Amazon). The blog post Share Your Kindle Notes and Highlights with Your Friends (Beta) describes the details of the functionality whose UI is pictured below.
- Some of the functionality offered includes
- Highlights and notes are private by default
- A slider on/off button to make individual annotations visible as well as one to make all annotations visible
- The ability to delete individual annotations
- The ability to add notes to each highlight online
- The ability to mark highlights and notes as spoilers.
- Third Voice
- An early attempt from 1999, done via browser plug-in, and suffered from the usual Tragedy of the Comments, closed in 2001.
- QuickTopic
- A site that mirrors another and allows per-paragraph comments
- Established 1999, closing down 2021
- Example page: the old mediagor site
Other Annotation Related Projects
In 2016/2017 Hypothesis was maintaining an active spreadsheet of sites and services that enabled annotation on the internet.
- VideoAnt
- VideoNotes
- Highbrow
- Resources in Mirador and from Third Parties
- Annotations at Harvard
- CommentPress Core a WordPress plugin that "allows readers to comment in the margins of a text. Readers may comment paragraph-by-paragraph, line-by-line, block-by-block or by selecting text." (Github)
- The Annotated Grateful Dead Lyrics the web's oldest annotation project?
- YouTube had allowed annotations until 2019-01-15 [1]
W3C Recommendations
On 2017-02-23 the W3C published several inter-related recommendations based on the notes of the Web Annotation Working Group. For some discussion on them, see Annotation is now a web standard post on Hypothes.is blog.
Despite being published as W3C Recommendations, there has been very little actual support in the wild for these W3C specifications, outside of Hypothes.is, which has essentially become a dominant silo for W3C-spec annotations.
Criticism
Annotation Sites Enable Abuse
Many web-based annotation programs/applications only allow the communities or subgroups who are aware that they exist to see the annotations, thereby making them available for potential abuse.
See specifically:
- 2016-03-25 : How News Genius Silences Writers (archived)
- 2017-04-26 : Un-Annotated (archived)
- 2017-06-24 : More Thoughts on Annotations (archived)
- 2017-06-27 : Thoughts on Audrey Watters’ “Thoughts on Annotation” (archived)
Webmentions could be used to help remedy this potential problem:
Brainstorming
Chris Aldrich has been experimenting since 2018-06-22 with PESOS of highlights and annotations using Hypothes.is to his own website for use as part of his commonplace book. Using Post Kinds Plugin he has created some custom post types for being able to post highlights and annotations as specific post types to his website.
- Examples of highlights can be found here: https://boffosocko.com/kind/highlight/. (Note: These were ultimately subsumed into annotations, see just below).
- Examples of annotations can be found here: https://boffosocko.com/kind/annotation/
- After some initial experimentation, he's considering concatenating the two different types (highlights and annotations) into just one catch-all (annotations). He's also been considering using a yellow "highlighter color" in his UI to mirror the physical world incarnation of ubiquitous pen-like ink highlighters as is sometimes done in fragmention implementations.
- Sometimes he prefers to create read posts under which he includes the highlights and marginalia from the material he's read. (example)
- In all cases, he includes URLs when available and sends webmentions to the original pieces so that they might add in line marginalia as commentary if they prefer.
- Perhaps in the future he'll extrapolate this work using a POSSE workflow?
- He's used ideas and markup from quote posts to guide some of his thinking as well.
- William Ian O'Byrne has been doing some UI experimentation with annotations: Three examples of annotations, bookmarking, & sharing in my digital commonplace book
Jeremy Cherfas distinguishes between annotations, which are notes created by a reader for their own use, now and in the future, and other kinds of response, which may be directed more at the author of a piece or other readers of that piece. He is old-fashioned about using annotations to build and make sense of his own knowledge archive. These annotations may eventually find their way into published pieces, but in essence are private responses to the piece in question and its relationship to other pieces.
Chaitanya started experimenting with annotations using Hypothes.is. The Hypothes.is user RSS feed is syndicated back to the website using IFTTT and webhooks.
Sessions
Sessions at IndieWebCamps
See Also
- marginalia
- comments
- interactions
- fragmentions
- W3C Web Annotation WG (Previously: W3C Open Annotation Community Group)
- http://annotatorjs.org
- highlight
- quotation
- https://thenextweb.com/media/2013/08/06/who-needs-a-comment-thread-quartz-now-lets-readers-annotate-articles-paragraph-by-paragraph/
- Exploring the UX of web-annotations by Tom Crichlow
- https://www.cjr.org/analysis/dissenter-plugin.php
- Annotation, a book by Remi Kalir and Antero Garcia from MIT Press that was open for annotation prior to publication.
- https://www.cjr.org/analysis/dissenter-plugin.php
- The mother lode of why and "how to annotate literally everything" https://beepb00p.xyz/annotating.html
- https://twitter.com/chrisbiscardi/status/1276405154778984449 Interesting UI example that could be done for annotating pages
- "I added "tweetable selections" to http://christopherbiscardi.com today. You can select some text to see an affordance that will send you to Twitter with the URL of the page you're on." @chrisbiscardi June 26, 2020
- Example from IndieWebCamp 2020/West https://chaitanya.page/categories/annotations
- Learning Paths - Chrome-based online highlighter/annotations
- Highlighted iOS app for creating book highlights and notes
- https://www.markup.io/, a silo product for visually marking up, annotating, or replying to web pages
- https://interconnected.org/home/2021/03/22/social_attention
- 2013-08-19 TechCrunch: Diigo, A Tool For Highlighting And Adding Sticky Notes To The Web, Gets A Facelift
A survey by Hypothes.is shows that of 56 companies that tried to build annotation tools, most are either Defunct, Living Dead, or have Limited Use.
- 2021-09-30 Mozilla dev-platform thread on "In-browser annotation": https://groups.google.com/a/mozilla.org/g/dev-platform/c/NXvLZHeIqQw/m/PbGve3rRAwAJ
- https://www.houstonchronicle.com/projects/2022/roe-opinion-annotated/, UI example of a site creating highlights and pop up marginalia to comment on text
- Molly White’s annotation site code: https://github.com/molly/annotate
- CritLink: Public Web Annotation by Ka-Ping Yee (prior art of online annotation)
- https://weblog.anniegreens.lol/2024/05/improvements-to-citations-with-footnotes-and-endnotes
- "Improvements to citations with footnotes and endnotes.
I wrote about adding microformats citations to weblog last November during NaBloPoMo. Then last week, I saw some discussion about footnotes again, replied with a link to my post, and began investigating some of the other solutions I saw mention of. One of them led me down the path of a couple EPUB related role attributes and I decided to go ahead and add them. Let's take a look at what I did through the updates I made to my recent CSS Color Modules and Changes, Part I post.
Existing citations
Implementation of microformats citations will go unhindered, but here's a light refresher of where I started. The h-cite property resides on a list item and contains one or more of the following properties:
dt-published
p-author and h-card
p-publication
u-url and p-name
Here is an example from the referenced CSS Color Modules post above, minus the updates (added below):
[4]
,
,
Chrome for Developers,
Migrate to HD CSS colorGraceful degradation: Use the new color spaces and let the browser and operating system figure out which color to show based on display capabilities.
- <aside role="doc-footnote">
[4]
,
,
Chrome for Developers,
Migrate to HD CSS color
</aside> Graceful degradation: Use the new color spaces and let the browser and operating system figure out which color to show based on display capabilities.
Progressive enhancement: Use
@supportsand@mediato assess the capabilities of the user's browser, and if conditions are met, provide wide gamut colors.[4]
You should also note that the u-url and p-name reside on an inside of a element. This citation matches the cite attribute on the citation reference on either aor
Footnotes
From what I understand, the EPUB epub:type attribute usage is being replaced with ARIA roles for accessibility: This document provides guidance for publishers looking to move from the use of the EPUB 3 epub:type attribute to ARIA roles for accessibility.[1]
That quote is from the abstract of this document, and goes on to explain:
The biggest of these differences is in their primary applications. The epub:type attribute has evolved to aid publisher workflows. It has limited use enabling reading system behaviors outside of some core functionality of EPUB (identifying navigation elements and enhancing media overlay documents). Although it was hoped the attribute would also expose information to assistive technologies, in practice it does not.The primary purpose of the role attribute, on the other hand, is to expose information to assistive technologies. It is not to facilitate user agent behaviors.[2]
The two roles I am concerned with for citations are complementary to the two parts of what I've already implemented: the citation reference and the citation note; these are: role="doc-noteref" and role="doc-footnote". The recommendations for each have some stipulations as follows.
doc-noteref
A reference to a footnote or endnote, typically appearing as a superscripted number or symbol in the main body of text.[3]
HTML usage:
doc-footnote
Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text. The doc-footnote role is only for representing individual notes that occur within the body of a work. For collections of notes that occur at the end of a section, see doc-endnotes.[4]
HTML usage: aside element when identifying a single footnote, or on descendants of sectioning content when identifying individual footnotes in a group (refer to footnotes and endnotes)[5]
From this information, I am a bit torn on the requirements, as they seem to slightly contradict each other. You'll see how I've decided to implement this (for now) under Template updates, but I am open to clarity and improvements if this method proves incorrect or incomplete.
Endnotes
In addition to proper citations relating to references, I also regularly include additional resources and links at the end of most blog posts. This is where I may eventually end up, after adding the requirements for role="doc-footnote" usage, as I believe the better method is to stick with role="doc-endnotes" as the containing section and role="doc-endnote" for each item.
doc-endnotes
A collection of notes at the end of a work or a section within it.[6]
Important context: Note that the doc-endnotes role is never applied directly to the list of endnotes. See the doc-endnote role for more information.[7]
This context is important because giving roles to elements can override their inherent nature, such that adding a role to a list element itself will override its role as a list. This will then cause issues with child elements' roles as listitem. Along these same lines, it is no longer necessary to add the role doc-endnote to a list item in a containing doc-endnotes section: [t]hese roles are now implied on list items within sections that have a...doc-endnotes role.[8] However, as I cover in the next section, I have added both roles.
doc-endnote
One of a collection of notes that occur at the end of a work, or a section within it, that provides additional context to a referenced passage of text.[9]
Important context: Authors MUST ensure that elements with role doc-endnote are contained in, or owned, by an element with the role list.[10]
If you understand the context in the previous section, the above context should also make sense: doc-endnote must be a child of an element with the role list, either by default through being an HTML list such as- or
- , or by having an explicit role of list assigned. My usage of both doc-endnotes on the sectioning element and doc-endnote on the list items may be redundant or unnecessary and I may end up cleaning this up. For now let's see how all this looks together in the template updates I made for weblog.
Template updates
The updates needed on weblog pretty much exclusively apply to the default post template in config. Since I am using Drafts for weblog authoring, I have both a recipe and post template, the post template mimicking the default post config in weblog, so I'll need to update all three templates.
I've added a sectioning element with role="doc-endnotes" and role="doc-endnote" to the list items. The ... denotes omitted content in the default post that is not relevant.
Default post: <<[---
...
---
<section role="doc-endnotes">Post info
Links in this post:
POSSE copies:
</section>
--- ]>>
For reference notes and citations, here is an updated example from the CSS Color Modules post above:
Additions to this citation note: a role="doc-endnote" on the list item and a nested <aside role="doc-footnote">.
This reference includes the addition of a role="doc-noteref" on the citation reference link.
As you can see, my updates include some redundancy and possibly incorrect markup: addition of the <aside role="doc-footnote"> even though part of the recommendation says to only use this on a single footnote within the "body of a work." I chose to include it because of the conflicting recommendation to use on descendants of sectioning content when identifying individual footnotes in a group.[11] Additionally, I included role="doc-endnote" even though that role is implicit on a list item within a sectioning element with the role doc-endnotes. These can all be updated and refined when I find clarity on this information.
Update: Isn't it just like publishing a post and a few hours later coming across something to change your mind? Well, I've found the thing I needed to make me definitively remove role="doc-endnote from the list items. In the W3C Candidate Recommendation, published February 27, 2024, doc-endnote is listed as deprecated with the following note:
The doc-endnote role was designed for use as a list item, but due to clarifications in the WAI-ARIA specification, it is not valid as a child of the list role. As the doc-endnotes role already identifies a section of endnotes, authors are instead advised to use the list and listitem roles when native HTML elements cannot be used to structure the entries.[12]
Secondly, within the same document, the recommendation is now unequivocally to not use doc-footnote within the endnotes as it is redundant. I also appreciate the addition of mentioning that multiple and separate lists of endnotes can be contained within the doc-endnotes sectioning parent.
The element carrying the doc-endnotes role MUST contain at least one descendant list containing the endnotes (if the notes are subdivided, for example by chapter, the element would contain more than one list).Authors MUST NOT declare elements with the role doc-footnote within the endnotes as it is redundant with the implied role.[13]
After leaving this post feeling quite unsettled with how I left things, conflicted by what I had found (and documented above), this feels like a 180° turnaround just a few hours later!
Post info
Citations in this post:
[1]
[2]
2023-03-14,
W3C Group Note,
EPUB Type to ARIA Role Authoring Guide
[3]
2024-02-27,
W3C Candidate Recommendation,
Digital Publishing WAI-ARIA Module 1.1: doc-noteref (role)
[4]
2024-02-27,
W3C Candidate Recommendation,
Digital Publishing WAI-ARIA Module 1.1: doc-footnote (role)
[5]
[11]
2023-12-21,
W3C Group Note,
EPUB 3 Structural Semantics Vocabulary: footnote
[6]
[7]
2017-12-14,
W3C Recommendation,
Digital Publishing WAI-ARIA Module 1.0: doc-endnotes (role)
[8]
2023-03-14,
W3C Group Note,
EPUB Type to ARIA Role Authoring Guide 1.1: 3.5 List roles are for lists
[9]
[10]
2017-12-14,
W3C Recommendation,
Digital Publishing WAI-ARIA Module 1.0: doc-endnote (role)
[12]
2024-02-27,
W3C Candidate Recommendation,
Digital Publishing WAI-ARIA Module 1.1: doc-endnote (role)
[13]
2024-02-27,
W3C Candidate Recommendation,
Digital Publishing WAI-ARIA Module 1.1: doc-endnotes (role)
Links in this post:
Diving into indiewebify.me & microformats, Part VII
CSS Color Modules and Changes, Part I
EPUB Type to ARIA Role Authoring Guide 1.1
Digital Publishing WAI-ARIA Module 1.1: doc-noteref (role)
Digital Publishing WAI-ARIA Module 1.1: doc-footnote (role)
Digital Publishing WAI-ARIA Module 1.0: doc-endnotes (role)
Digital Publishing WAI-ARIA Module 1.0: doc-endnote (role)
Digital Publishing WAI-ARIA Module 1.1: doc-endnote (role)
Digital Publishing WAI-ARIA Module 1.1: doc-endnotes (role)
POSSE copies:
Shared on social.lol
Shared on Apple Annie's Microblog
Share this post on social media.
Discuss on Mastodon" @Author: Anne Sturdivant May 12, 2024 - "Improvements to citations with footnotes and endnotes.