Annotation Design and UX

Hi, folks–

Renoir has deployed the Hypothes.is Annotator app [1] on our site, at 
notes.webplatform.org [2].

He's also updated the page templates for the static pages 
(www.webplatform.org) and docs.webplatform.org to include the script 
reference to the annotation insertion script, so annotations are now 
(experimentally) available on every page.

This will replace our existing MediaWiki custom comments extension; 
that's the per-section comments dialog we have now, which you can see 
next to some section headers. For now, they will live side-by-side; I 
hope this transition will be short-lived. We can disable the MW comments 
extension, but we should consider porting over existing comments to the 
new annotation system; automating this task is probably easy, but some 
of the comments may be old, so we should consider if this is what we 
want to do.

As an example of each, you can see the SVG <use> page [3]. On the right 
side, you can see the new annotation sidebar (I made one annotation with 
a reply); on the Overview section, you can see a comment on the header [4].

There are 4 main differences between these annotation/comment systems:

1) UI (as mentioned): the comment extension has a per-section dialog 
with the indicator and "start annotation" button on the header, while 
the annotation app has a sidebar containing the annotations and 
annotation indicator marker, with a "start annotation" button anywhere 
you have selected text;

2) Scope: the comment extension only allows you scope comments at the 
section level, and doesn't have a mechanism for including a quote, while 
the annotation app lets you select a specific passage anywhere on the 
page, and scopes the comment to that, which will allow easier

3) Data access: we had intended for WM comments to have a collected 
comments page in MediaWiki, but that feature was never implemented; 
however, the annotation app has a dedicated view for each annotation 
[5], as well as an activity stream view of all the annotations [6], 
which is searchable with various filters, including user [7], tags, 
time, and other facets, using ElasticSearch;

4) Architecture: the current comment interface was a custom MediaWiki 
extension built for us, and it used the MediaWiki database to store the 
comments, while the annotation app is a standalone app with its own data 
store; the downside of this is that we will have to do some extra effort 
to enable single-sign-on (SSO) so that you have a single username and 
don't have to log into each app separately; the big upside is that the 
annotation system can (and will) be improved independently, and all the 
annotations will persist in case we move to another CMS.

This independent architecture will also allow us to annotate not only 
content on WebPlatform.org, but also W3C specs, and if you install the 
extension or bookmarklet, even other specs or pages from around the web, 
which will allow us to take inspiration and information from various 
different sources to improve WPD.


You can see from the Annotator pages that is the default installation, 
and still retains the Hypothes.is branding [2][5][6][7]. I'd like to 
change this very soon to WPD branding, so we don't confuse users. I'd 
also like to make this a more integrated experience overall for the WPD 
site.

Short-term: we should change the logo, colors and other style of these 
pages, as well as the content on the Annotator landing page [2]. This 
should be pretty easy. (Jen, is this something you could do?)

Medium-term: we should look at how the expanded (open) sidebar (which is 
an embedded <iframe>) affects the page; currently, it just overlays the 
page, overlapping with the content, but I think the page contents should 
actually shift over, decreasing the margins, so there's no overlapping 
content; I don't know how hard this would be to do. (Jen, any thoughts?) 
We also need to address how the annotations appear on mobiles (I think 
it might be best to shift the sidebar to align horizontally along the 
bottom of the page, with its own scrollbar).

Longer-term: more substantively, we should start adding features to the 
Annotator that enable tighter integration and workflow improvements to 
the site, leveraging the ElasticSearch engine and Frozenice's bot framework.

Once we feel we are in a stable place with this new annotation system, 
we should write up a blog post.


Any thoughts or reactions?


[1] https://hypothes.is/alpha/
[2] http://notes.webplatform.org/
[3] http://docs.webplatform.org/wiki/svg/elements/use
[4] http://docs.webplatform.org/wiki/svg/elements/use#Overview_Table
[5] http://notes.webplatform.org/a/7oTdmXbvRS-yFzUnOgPyVQ
[6] http://notes.webplatform.org/stream
[7] http://notes.webplatform.org/stream#?user=Shepazu

Regards-
-Doug

Received on Sunday, 9 March 2014 23:40:53 UTC