[annotator-dev] Notes on Annotations from seminar

[Randall Leeds]

Sorry for top posting (also, I'm cross-posting to annotator-dev), but
you all wrote small novels here.

I'd just add that Hypothes.is is still very much built on top of Annotator.

In the past week I have broken out two plugins: *

- Threading [0]
  This implements discussion threading on annotations and has only one
outstanding code dependency in the h application that I think I can
eliminate by a non-invasive change to Annotator. It requires jwz.js
[1] for the `mail.messageThread()` function. The rest is implemented
through vanilla Annotator events, though currently the Annotator
viewer doesn't know anything about the threads, it could be made to.

- Cross-domain bridge [2]
  This lets us implement our UI in an iframe with minimal changes to
the main application. It provides an easy way to share annotations
between widgets. It depends on jschannel [3]. I'd like to expand it in
any way that's helpful. Eventually, this could lead to mashups of
annotation tools. There's lightweight extensibility provided through
the configuration for fine-grained sharing and merging of annotation
properties across browser security domains and windows.

I also just took 15 minutes and proved to myself that I could
re-enable the Annotator bubbles with our sidebar on the page as well.
It was easy. At this point, most of our code is not overriding
Annotator in complex ways anymore, but augmenting it in surgical ways,
or overriding methods to simply disable features straight away (such
as the editor and viewer widgets). I'll open some issues for making
this configurable and for documenting our embed code. We can start to
flesh out the integrations.

I'll see what I can do to break our sidebar widget out into a separate
plugin as well, so that the embed code can be a normal Annotator embed
with a custom plugin config and some additional CSS.

In other words: ** Don't worry so much about designing one right
thing. Let's design (and implement) many things. **

You should not view these interfaces, Hypothes.is and vanilla
Annotator, as mutually exclusive!

That said, all the feedback is *greatly* appreciated.

So: Yo, dawg. I heard you like annotations, so why don't we get some
accounts turned on and we can start annotating some PDFs about
annotation interfaces?

-R

* This stuff still needs to bake a little bit and solidify and we'll
try to get it all working with upstream Annotator. Everything needs
tests. Patches welcome. Offer extends forever.
[0] https://github.com/hypothesis/h/blob/develop/h/js/plugin/threading.coffee
[1] https://github.com/maxogden/conversationThreading-js
[2] https://github.com/hypothesis/h/blob/develop/h/js/plugin/bridge.coffee
[3] https://github.com/mozilla/jschannel

On Tue, Mar 19, 2013 at 7:35 PM, Dan Whaley <dwhaley at hypothes.is> wrote:
> Jake,
>
> Thanks for taking the time on these notes below, it's really appreciated.
> I'll respond inline below and cc this to our dev list for the benefit of
> others that are helping us think through these same questions.
>
> On Mar 19, 2013, at 4:07 PM, Jacob Hartnell <jake.hartnell at gmail.com> wrote:
>
> Hey Dan,
>
> Here's some of the notes I've pulled together from research I've been doing
> over the past couple of days. Forgive me if many of these things are either:
>
> Obvious
> You already know them
> Are part of upcoming plans and just haven't been implemented yet.
> Poorly articulated (in which case, I can rephrase them)
>
> What you've laid out is actually very clear.  Thank you.
>
> At the moment, we are actually still considering using Hypothes.is (there
> are certain elements of the UI we prefer, especially for shared
> annotations), but I do have some feedback for you.
>
> Annotation changes a great deal between use cases: Students in classrooms
> will use hypothes.is differently than scientists doing peer review on an
> article. In our use case students will be making annotations on top of the
> book. As simple as this sounds, it's a bit complicated and that's what I
> hope to flush out in this email.
>
> In the classroom there are actually two different use cases at hand: private
> note taking verses online class discussion. Private note taking is very
> different from shared annotation that takes place in class discussion or
> collaborative annotation. In From Personal to Shared Annotations (attached),
> one of the authors noted, "People often annotate paper documents as they
> read them, especially if they are responsible for assimilating the content.
> They underline text, write notes in the margins, place asterisks by content
> they want to find again, and otherwise create a personal geography of the
> reading materials." Other studies have also noticed that the great majority
> of personal annotations are simply highlights or underlines.
>
>
> (I'll just mention as a side note, that Cathy Marshall, the principal author
> of the paper you cite above will be attending and speaking at the workshop
> in April.)
>
> One of our primary objectives, and our engagement strategies is to design a
> high quality personal research tool based around annotations, highlighting,
> tagging and so forth.  I believe I mentioned some of this in my presentation
> Saturday, but let me point out a few things.
>
> 1) We just launched personal annotations to our dev branch last night and
> are testing it internally.  We think of this as "visibility".  Personal,
> private group or global channel.  Groups will come a bit later this spring
> or early summer.
> https://github.com/hypothesis/h/wiki/visibility
>
> 2) We have a number of additional features targeted at our Personal research
> releases A & B on our roadmap.  They include a "my annotations" view,
> various sorting and filtering options, PDF support (just launched this
> weekend), highlighting and favoriting.  Also, the ability to link to an
> annotation.
> https://github.com/hypothesis/h/wiki/Roadmap
>
> 3) We think we understand some of the key features that people want, because
> we've heard others ask for them, or they seem intuitively obvious-- but we'd
> love your perspective on this, and any further guidance you have to offer.
> We know we haven't thought of everything-- far from it.
>
>
> I think there's a difference between annotations as reading and annotations
> as writing. When participating in discussion around an area of the text,
> more thought is put into a post. Private annotations are different, and I
> think Hypothes.is should equally address them as well as it doesn't shared
> annotations (since annotations can easily move from private to shared).
>
>
> Completely agree. :)
>
> I'd even go further:  We *won't* succeed unless we are also a high quality
> personal research tool.  And yes, per the below-- you'll be able to toggle
> visibility.
>
>
> UI notes:
>
> The UI doesn't support highlighting very well. Obviously, for the overall
> mission of hypothes.is this isn't as important as the discussions but for
> use in our application it's really important. A lot of students highlight
> without making a comment. In addition, this is not necessarily content that
> students want to share (except to show in aggregate, perhaps like the Kindle
> does—"122 people highlighted this passage").
>
> Highlighting is covered under linking here-- though it may need its own
> stub.  There are some sketches, a few  contributed by a recent volunteer,
> Abel, that we haven't fully assimilated ourselves… not finished by any
> means.
> https://github.com/hypothesis/h/wiki/Linking-to-an-annotation
>
> There needs to be a private annotation mode. Moreover, it should be easy to
> switch between private and shared annotations. It also should be optimized
> for the differences between personal annotation and shared annotation.
>
> One of the reasons we've leaned towards annotator, is that while the layout
> isn't as optimized for shared annotation and discussion, it's better suited
> towards private annotation, and allows us to support both… though it's also
> far from ideal in this regard.
>
> We don't think of it as being in a mode, we think of creating annotations
> that have different visibilities.  You can take a previously private
> annotation and toggle it to globally visible.  That may be a one-directional
> move?
>
> Better support/UI integration for different annotation flavors: comments and
> highlights.
>
> Students don't always attach a comment to a text selection.
>
> Yes, this is targeted for the "advanced editing" set of features on the
> Roadmap.
>
> (I'll just say here that the feature sets on the roadmap are just
> approximate groupings of related elements for the purpose of organization--
> in actuality, we'll gather elements from these various groups into releases
> as we move forward.)
>
> Especially while reading, most students only highlight with no comments.
>
> Check out the highlight feature in Mac OSX Mountain Lion Preview, maybe in
> "private mode," annotations could support highlighting with different a
> similar workflow.
>
> Highlighting, per above.  Happy to review different design approaches.
>
> Different color highlights need to be easily supported.
>
> Sure.  Color might be a kind of tag that carries a style with it.
>
> Tagging also needs to be easily supported, our experiment relies a lot on
> the ability to use tags. Annotator has this functionality which is one of
> the reasons we were considering using it over Hypothes.is.
>
> "Advanced editing" on the roadmap.  Again, anything in annotator is already
> available to hypothes.is at the storage layer.  Thus, the only thing that
> needs to be created is the UI to support it.  This is not too terribly much
> work, but we need to think through exactly the approach we want to take.
>
> For example, we wanted to have a "flag" tag. If you flag a portion of the
> text there is something wrong with it. Either, it's not useful, unclear, or
> contains an error. This data is not shared with the class and used to help
> improve the textbook.
>
> Our thinking is that this goes in a "moderation release".  We have some
> really rough early mockups.  Flagging we imagine might be highly
> customizable.
>
> Students in classrooms will use hypothes.is differently than scientists
> doing peer review on an article. Permissions need to be an essential part of
> the flow. It needs to be easy to switch between personal and shared modes.]
>
> Seamless.
>
> There also needs to be an easy way to create, join, and switch between
> shared annotation groups. (Obviously you are working on the group
> functionality)
>
> Groups. Yep.
>
>
> Here are some other things I've found in some articles I've read lately
> (I've attached them to the document and highlighted some interesting
> passages). I think Hypothes.is does a pretty good job of addressing them,
> but there's always room for improvement. [My thoughts are in brackets.]
> These come from section 6.4 of the Annotation thesis I attached.
>
> Developers should focus on designing annotation systems that present the
> best, most productive annotations rather than attempting to display all
> annotations made (Wolfe, 2008). [It should be easy to switch between
> different modes (private, group, top-rated, everyone)]
>
>
>
> Yes, this lumps together very distinct concepts though:  private & group
> modes are visibility related, "top-rated" is a sort criteria on what you can
> see.  everyone is the third visiibility parameter… i call it the global
> channel.
>
> ON/OFF: Participants expressed the view that it is absolutely critical that
> readers could turn the annotations off very quickly and easily, perhaps in
> one single click.
>
> Once we launch the extension this week or early next, you will see that even
> the sidebar is not active until the extension page action icon is clicked.
> i.e. We agree.
>
> This functionality should also probably be reflected somehow in an
> embeddable version of annotation, without the extension-- maybe simply via
> an icon or other element of the web page we're embedded on.
>
> It would also be important to have the annotations turned off by default,
> because annotated texts distract the readers, especially the first-time
> readers. [Though the heat map and the pointers are cool and fairly
> unobtrusive on a website, in a book they can still be annoying/distracting.
> Perhaps by clicking on the discussion box icon they can be toggled on/off.
> Every reader is different, but this bothers some people. Usually, people
> want to read an article or chapter first AND THEN check and see what others
> are saying about it.]
>
>
> Yes, per above.
>
> DON'T HAVE TOO MUCH ON SCREEN: In their study of annotation layouts,
> Zellweger, Regli, Mackinlay, and Chang (2000) found that many readers
> objected to annotations that interrupted the flow of the primary text.
> Cabanac et al. (2005; 2007) moreover noted that interlinear annotations may
> potentially be confused with the primary text. [You guys do a pretty great
> job at this!]
>
>
> Thank you. :)
>
> Keep sending me questions and I'll do my best to find answers and opinions
> on them. In general, the feedback to hypothes.is has been really positive!
> It's exciting to watch the progress on it.
>
>
> Great!
>
> I'm really glad there's an opportunity to work together.
>
> Sincerely,
>
> Jake
>
>
>
>
> <p812-marshall.pdf>
>
>
> <AnnotationThesis2010.pdf>
>
>
>