Implement highlighting mode

[csillag]

As described in this specification

[csillag]

Let's discuss this specification.

I have described my understanding of the specification, along with my questions. Since the text is long, instead of dumping it here, I have created a Google document out of it.

Please comment, either here, on at the document; confirm that my interpretation of the specs is right, and answer my question :)

[JakeHartnell]

I made some comments on the Google doc. Overall, your understanding is really good. There are a few clarifications in the document comments, let me know if you have further comments!

[csillag]

Since most of my questions have been resolved, I am moving the discussion about the remaining issues here.

Visibility

There are two things that influence how the highlights made by other users impact me:

Privacy settings of the existing highlights

As already discussed, when working in highlighting mode, highlights will be created with the visibility set to private. This means that (unless they are explicitly published by the author) other users won't see them.

This feature is not limited to highlighting mode; it works just the same with normal annotator, except that in normal mode, the default privacy settings is public.

Filtering settings of the user

Currently, if something is public, and it's on the page that I am working on, I will see it. Eventually we will want to change this; see #535 for the proposal about Social Views. Again, this feature is not limited to highlighting mode, except that we might want to turn on some social filters by default. (When it gets implemented. Probably not before V2 only.)

Question: Are these two levels of filtering enough? I think they are. That means we don't have to do any other kind of filtering that is intrinsically bound to the highlighting mode, right?

Question: Should it be possible to publish a highlight at all? I think it should be. My reasoning is the following:

• Generally, I hate to break symmetry, or to introduce arbitrary restrictions. I think annotations and highlights should be treated equally, whenever possible.
• Publishing a highlight (and then sharing the link to it) is a great way to share interesting things one finds on the net with others!
• Currently, we are supporting this (public, highlight only annotations). In fact I am already using this feature to share stuff with others. To remove this feature would be a step backwards. What is the reasoning behind allowing me to publish an annotation that is basically a long quote, and my comment being "this is great", but not being able to publish the highlight without my meaningless contribution? This is the kind of arbitrary restrictions that tend to crop up in proprietary software, for some narrow-minded marketing reason, and which everybody hates.
• What happens when I create an annotation (in public mode, by default), and share the link, and then I decide to remove the body, and thus I convert it into a highlight? Should it automatically (and unavoidably) turn to private? Why?
• In the end, people will still do it, even if we don't allow this; they will just have to add a stupid pseudo-body to the highlight. For example, a dot. Does that make our product better? I don't think so.

[csillag]

Elaborating my reasoning (for not killing the ability to publish highlight-only annotations):

• I think adding arbitrary restrictions makes it harder for the users to grok our product. They will search for the setting to make some highlights public, but to no avail (first phase). Then they will ask us about it. And when they realize that we have removed it by design, they will get pissed (second phase), and then they will realize that they can circumvent this limitation by adding a useless body, and start doing so (third phase). I would hate to intentionally get in the way if our users.

[csillag]

UI questions

Question: Should highlight-only annotations appear on the sidebar? I think they should. My reasoning is the following (will be slightly similar):

• Generally, I hate to break symmetry, or to introduce arbitrary restrictions. I think annotations and highlights should be treated equally, whenever possible. I think it would be confusing
• There is some useful information that is displayed here: how made this highlight, and when?
• The annotator stub displayed at the sidebar can be used as a platform for various user operations, like
  • change color (in v2)
  • add body ( = edit)
  • add tags ( = edit)
  • reply to highlight
  • change privacy settings (if supported, see discussion above)
  • share highlight (if supported, see discussion above)
  • delete highlight
  • go to detailed mode, to show all tags and replies

Yes, we could dream up some controls for most of these operations that can directly embedded in the pop-up menu, but I think it would be way more difficult to implement, and also needlessly redundant. That's what the sidebar is there for!

[JakeHartnell]

You've convinced me on the ability to publish a highlight publicly... though I'm not sure if we were communicating properly because we (Dan and I) did envision a way to share highlights (such as being able to link to them). The principle we were going for was to reduce "clutter" on the public channel. What we didn't want is a situation on a popular document where the whole thing winds up being highlighted and there are more bodiless annotations than proper annotations.

Still, I could see a few useful cases, such as in certain groups, where the ability to make public highlights would be a plus. I also like the symmetry you talked about, that annotations and highlights should be treated equally when possible. So let's give it a try and do some user testing to see what people expect/think/do.

As for whether highlights should show up in the sidebar... I have mixed thoughts. Initially, we had looked at studies by Cathy Marshall showing that people highlight MUCH MORE than they annotate (provide a comment with their selection). If we want the sidebar to be a place for discussion, having too many bodiless annotations could be a minus. That is my concern.

Perhaps a filter to show only annotations with a body?

Your thoughts?

[csillag]

About public highlights

I do share your concern about clutter; I just don't think that taking away features is the right answer to that. I think this should be handled by

• Introducing a finer-grained model of visibility/accessibility; see my thinking in #536
• Introducing filtering for the users. (Social mode is one good direction; there are possibly others, too.)

[csillag]

About highlights in the sidebar

• I think they carry valuable information. (author, time, tags, replies).
• I don't see the point of showing the highlight in the document, but omitting the related information in the sidebar. (Again: author, time, tags, replies.) Not showing the highlight in the sidebar also makes it very hard to perform operations on it.
• I think we can reduce the amount of annotations/highlights shown on the sidebar/document with finer-grained model for visibility (see my proposed humble mode in #536 ), and by adding filters.

[JakeHartnell]

Ok, let's try it your way. Anyone else have thoughts on this?

[tilgovi]

:+1:

[tilgovi]

We could, for instance, group highlights together in the sidebar, and only show more detail about where there is more or less overlap between each user's selections after expanding the group.

[csillag]

Question: when highlighting mode is on, should there be a visible indicator somewhere in the app?

[dwhly]

Good question. I've thought that the control bar buttons could potentially serve that role. Imagine that if the highlight mode is activated and the button is locked on, then the button stays visible as selected even when the cursor rolls back off the control bar. Some nice CSS transitions could ensure that the button stays high and tight to the toolbar tab even if it's not the first in sequence.

We'd probably want the heatmap to shrink slightly in length so that it only filled the slightly shorter space then available.

Thoughts?

[csillag]

Clarification: it has been decided the minimal Social Views support (#535) must be part of highlighting mode, as early as V1.

[csillag]

About the visual indicator: for the time being, I simply styled the highlighting mode button red when the mode is on. I will leave the fancy indicator described by @dwhly to @RawKStar77.

[csillag]

Sub-task list:

• [x] support for persistent highlights
• [x] support for creating highlights with just a swipe of the mouse
• [x] Make the newly created highlights private
• [x] when hovering over an annotation in sidebar, make the highlight in the host document "pop"
• [x] support for selecting the highlight on the sidebar by clicking on the highlight inside the doc
• [x] implement forced login (instead of telling the user to do so manually)
• [x] forbid publishing highligh-only annotations
• [x] UI polish: new icons and control bar interactoin
• [x] UI polish: highlight card
• [x] Implement separate always-on mode
• [x] social view integration
• [x] Fix bug: when clicking on a highlight, sometimes several other cards stay on the sidebar. (All else should disappear.) - broke out to #621
• [ ] Internal clean-up: move some stuff from the bridge plugin to other places, etc.
• [ ] yellow for highlights only, blue for annotations. - maybe for V2
• [ ] support for deleting from context menu - maybe for V2
• [ ] support for editing from context menu - maybe for V2
• [ ] support for setting privacy from context menu - maybe for V2

[JakeHartnell]

This is what the highlight card should look like:

Note: the highlighter icon can be found in the pull request I submitted: 570

It's css class is .hightlighter-icon

[csillag]

This is for the sidebar, right?

How about creating some mock-ups for highlights shown at the standalone displayer page, too? (Preferable with and without replies, and with and without tags. That would be 4 mock-ups total.)

[dwhly]

Since we're about to implement unified templates for things, so that there's consistency across the UI, not sure we should mock these up separately...

Based on convo on IRC-- resolved that unified templates will resolve these things. may have to hack consistent UI for now across streams, standalone, sidebar. First priority is to complete the feature, we can style later.

[csillag]

You can check out the new style (for the sidebar) at the usual place.

[csillag]

Fixed by https://github.com/hypothesis/h/commit/ddf17189fbf2d428b21fd31065a1c2d2bc6ab08b.