‘a note by way of explanation or comment added to a text or diagram: marginal annotations.’ Oxford Dictionary of English (ODE) on macOS

Documents and blocks

‘But, in general, as a reader, I want documents, as a writer, I want blocks.’

Gordon Brander subconcious newsletter

See also annotations as linked data, web annotations, Project Xanadu.

Text fragments

Making an annotation of specific text in a block or document, somewhere outside original block/text means we need to use something called stand-off markup.

This gives us great flexibility. The annotation can be private, or public, and we can change it without going back to the source. But as Gordon Brander points out, this is a brittle system that would crack if the original text changed.

Using something like Text Fragments gives us a ‘search string’ to mark an annotation. Meaning that we if we link to a block, with some specific text highlighted, we will get an annotation to that specific content until it changes. If the text ever does change, we still have a reference to the block, and a lossy specififity. A clever search algorithm could help us guess where we orignally meant the annotation to point to.

Further reading

Text Fragments. Draft Community Group Report, 29 December 2021

The Text Fragments proposal adds support for specifying a text snippet in the URL hash. When navigating to a URL with such a text fragment, the user agent can emphasize and/or bring it to the user’s attention.

Open Annotation Community Group