Hi list!
This Friday, I had a nice long call with Gerben about how we can work together
in the best way, covering our immediate needs and some reflections on where we
could go as an ecosystem. We've identified a few action points, but to put this
all into context, I'd first like to describe our use case.
First, we had the idea to create a version of the hypothes.is direct liking
feature with an improved UX. After some internal discussions and the call with
Gerben, we've decided that would be to risky in terms of providing a consistent
UX, dealing with illegal content and infrastructure costs. So we've decided to
allow the user to share a link to a highlight, which will be shown directly in
the page if our plugin is installed, but otherwise we'll show a page only
containing the highlight, with the title and logo of the original article, a
link to go there, and a call to action to install our plugin (UI mockup should
be available soon).
This means we'll use annotator to:
1) Generate an Annotation when a direct link is generated
2) Validate server-side whether the Annotation is present in the linked page
(it'd be great not to have to generate an in-memory DOM here and work directly
with the HTML string.)
3) Highlight the Annotation in the actual page from the plugin
When talking about annotations, sometimes I get confused about which terms to
use, so just to agree on a few terms here and if I'm on the right path:
* Annotation (capital A): An annotation object conforming to the W3C spec
* Selector: According to the W3C spec
* Anchor: The content specific position in a document of a selector, which may
be a selection object in a DOM object, or an XPath, string range, etc. (Also
referred to as Segment in the Wiki)
* Anchoring: Converting a selector to an anchor
As for the action items, the first priority seems to define a simple API. As a
consumer, I want to think about as little as possible, so as Gerben suggested
in the Overview page in the Wiki, it'd great to have just those two functions
that do everything for me. There are a few open questions:
1) How do we deal with different content sources? DOM, text string, image, etc.
Do we create different entry points for them, like anchorSelectorInDOM,
achorSelectorInString, etc.?
2) How do we deal with multiple selectors to make them redundant? Meaning that
if we have a CSS selector and the HTML changes slightly, we still have a
TextRangeSelector to fall back to.
3) How do we integrate fuzzy matching into the library? Do we allow for
multiple engines? What's the consumer-facing API: achorSelectorInString(...,
{exact: false})? What's the internal design of this?
Then, we saw that the search() function in the demo might actually belong in
the core library, and a better implementation needs to be written for this.
Another question, for you Randall, is how to easily develop these packages
locally? Normally when working accross multiple packages, I use 'npm link'. Is
there a better way for this, seeing that there are a lot of packages that work
together here?
That's all for now! Talking with Gerben, we said that it may be best to create
our own fork of Annotator so we can quickly go to production (we'll need to
start integrating Annotator in 1-2 weeks) while still being able to merge
efficiently up- and downstream.
I'm looking forward to making this work for all of us and to create a nice
implemtation of annotations that will hopefully be used by many, and to work
with you guys on this!
Best regards,
Vince
---- On Tue, 03 Apr 2018 10:35:46 +0200 Vincent den Boer <[email protected]>
wrote ----
> That's good news :) And yeah, I'm definitely up for a call! I'm located in
> the Berlin/Rome timezone, so that's GMT+2. The best for me in general would
be
> weekdays from Monday to Thursday, Monday 15:00 to 16:30 excluded.
>
> On maandag 2 april 2018 20:16:52 CEST Randall Leeds wrote:
> > I would be very comfortable tagging a 0.1 and voting for release in the
> > very near future. Would be good to get used to doing it often.
> >
> > On Mon, Apr 2, 2018, 12:59 Gerben <[email protected]> wrote:
> > > I have been wondering about the next steps myself, I'm eager to get at
> > > least the demoed functionality to a usable state soon. If you like, we
> > > could have a call one of these days?
> > >
> > > Randall &/| Benjamin, would you then like to join? Otherwise I'd be glad
> > > to catch up some other time with the two of you (and perhaps other
> > > interested people!).
> > >
> > > - Gerben
> > >
> > > PS for your interest, I think the term "direct linking" was inherited
from
> > > Hypothesis; via.hypothes.is is very similar to what you are making (as
> > > you probably already knew).
> > >
> > > On 02.04.2018 09:40, Vincent den Boer wrote:
> > >
> > > Hi Gerben,
> > >
> > > Thanks for your quick reply and for the very useful clarifications! The
> > > demos helped to get a more visual picture of what's going on.
> > >
> > > As for our use case, what we're implementing right now are 1) making
> > > annotations to any page through a web extension, to store them locally,
> > > and 2) making annotations, which are stored on a server and shareable
> > > through a link (which we internally call Direct Linking.) When such a
> > > link is followed, our server fetches the page from the stored URL,
> > > injects a script into this HTML to apply the stored annotations, and
then
> > > returns the page to the user.
> > >
> > > In short, we need the functionality demonstrated in the demo you've sent
> > > :) How can we help you to get this into a state where we can implement
> > > it? Is there a roadmap with important things to solve? From what you and
> > > Randall say, I believe we'll need to implement this before you ship the
> > > first version, so we'd be to contribute to get this project closer to a
> > > more stable state.
> > >
> > > Best regards,
> > > Vincent
> > >
> > > On zaterdag 31 maart 2018 00:36:19 CEST Gerben wrote:
> > >
> > > On 30.03.2018 12:31, Vincent den Boer wrote:
> > >
> > > Hi everyone,
> > >
> > > We're implementing a feature requiring annotations in WorldBrain.io, so
> > > I've begun looking into Apache Annotator. Scrounging the wiki and the
> > > website, I've come across links to AnnotatorJS and other projects, but
> > > have no idea how far Annotator has diverged from AnnotatorJS. Looking at
> > > the incubator-annotator I see some packages for anchoring annotations
> > > (docs anywhere?), but could anyone give me an idea how everything
> > > connects? As far as I've understood from the overview, Annotator's main
> > > job for now is to convert selectors into anchors, and vice-versa, right?
> > > Are there any more docs? And since I see no "index" key in the
> > > package.json, is it already meant to be used as a package? If so, what
> > > can we expect in terms of API stability?
> > >
> > > Thanks for your time!
> > >
> > > Best,
> > > Vince
> > >
> > > Hi Vincent; cool you are looking at Annotator, sorry for the state it is
> > > currently in. ;)
> > >
> > > As for the relation with AnnotatorJS: there is overlap in people and
> > > purpose, but it does not share any code. The approach this time is to
> > > make a library of smaller modules, rather than a framework for a whole
> > > annotation workflow. At least, that is my understanding so far.
> > >
> > > As you already noticed, we started making packages for creating and
> > > re-anchoring Web Annotation
> > >
selectors<https://www.w3.org/TR/2017/REC-annotation-model-20170223/#selec
> > > tors>
> > > <https://www.w3.org/TR/2017/REC-annotation-model-20170223/#selectors>.
> > > There is a simple demo in the source to show the idea; it can also be
> > > played with here <https://temp.treora.com/annotator-demo/>
> > > <https://temp.treora.com/annotator-demo/> (while it is not on the
> > > Annotator website yet).
> > >
> > > Regarding the readiness: it is not fit for using right away since only
> > > the very basic cases have been implemented, but the setup is all there
> > > to implement missing functionality. It mainly needs some more love to
> > > help get it going!
> > >
> > > Let know if you have more questions, want to share your use case, or
> > > have ideas to contribute.
> > >
> > > Cheers,
> > >
> > > Gerben
>
>
>
>
