Realtime annotation

[nickstenning]

As a user, I would like to see other annotations being made on the page as they are made, so that I can engage in a discussion without reloading.

Acceptance criteria

• If I have the sidebar open, and any other user creates an annotation on the page I'm looking at, it appears in my sidebar
• If I have highlights visible, and any other user creates an annotation on the page I'm looking at, the highlight appears in my view
• If any other user replies to an annotation in my view, their reply appears in the message thread
• The display updates in an appropriate way if any other user edits or deletes their annotations
• If I am currently creating an annotation I should not be interrupted by new annotations.

[aron]

Okay, I've been giving this some thought this morning. I think the implementation from a front-end perspective largely depends on the amount of annotations created.

The following assumes low traffic, under say 1 annotation every 30 seconds. Any more than this and we likely want to buffer annotations and show a notification that allows the user to manually trigger the the update, much like Twitter does on it's feed.

For insertions we have the following cases...

1. Insertion of a new annotations card. This should make space for the card then fade it into view (video).
2. Insertion of a new reply into a collapsed thread. This should "pulse" the background of the annotation card to indicate updates have been applied (video)
3. Insertion of a new reply. This should fade in the annotation much the same as the new card. The entire card color should pulse.
4. Insertion of a highlight. I think we should just insert this into the document. If highlights are visible then we can fade them in.

For edits I think we can just pulse the card for the moment.

For deletions there are two use cases...

1. An entire thread is removed. We should just fade out and remove the card.
2. A parent annotation is removed but it still has children. We should update the card content and pulse the background color to indicate a change.

There are still some outlying questions that we need to answer.

• What happens if an annotation is changed while it is out of view? My thinking is that the transition be suspended until it scrolls into view. Otherwise it would be easy to miss. This might be too difficult for a first pass at this feature though.
• What happens if a user is editing or interacting with the sidebar? I'd like to ensure that the view doesn't move around. Ideally if a user is interacting with a card it remains in place. Again not sure how difficult this is. The last thing we want is for someone to be creating an annotation and have the form pushed out of view by new annotations.
• Do we need an indicator of new annotations as they come in? Something like a badge near the search bar?

[aron]

Okay, I've been giving this some thought this morning. I think the implementation from a front-end perspective largely depends on the amount of annotations created.

The following assumes low traffic, under say 1 annotation every 30 seconds. Any more than this and we likely want to buffer annotations and show a notification that allows the user to manually trigger the the update, much like Twitter does on it's feed.

For insertions we have the following cases...

1. Insertion of a new annotations card. This should make space for the card then fade it into view (video).
2. Insertion of a new reply into a collapsed thread. This should "pulse" the background of the annotation card to indicate updates have been applied (video)
3. Insertion of a new reply. This should fade in the annotation much the same as the new card. The entire card color should pulse.
4. Insertion of a highlight. I think we should just insert this into the document. If highlights are visible then we can fade them in.

For edits I think we can just pulse the card for the moment.

For deletions there are two use cases...

1. An entire thread is removed. We should just fade out and remove the card.
2. A parent annotation is removed but it still has children. We should update the card content and pulse the background color to indicate a change.

There are still some outlying questions that we need to answer.

• What happens if an annotation is changed while it is out of view? My thinking is that the transition be suspended until it scrolls into view. Otherwise it would be easy to miss. This might be too difficult for a first pass at this feature though.
• What happens if a user is editing or interacting with the sidebar? I'd like to ensure that the view doesn't move around. Ideally if a user is interacting with a card it remains in place. Again not sure how difficult this is. The last thing we want is for someone to be creating an annotation and have the form pushed out of view by new annotations.
• Do we need an indicator of new annotations as they come in? Something like a badge near the search bar?

[dwhly]

The following assumes low traffic, under say 1 annotation every 30 seconds. Any more than this and we likely want to buffer annotations and show a notification that allows the user to manually trigger the the update, much like Twitter does on it's feed.

I'd support this if the rate was measured over some time (> 5 source level annotations over 30 seconds?) and not two annotations that just happened to come in at approximately the same time. Also, if its a collapsed card w/ the reply count updating that's much less intrusive. I'd probably just let those happen. Generally: Lets tend towards letting realtime happen, and see when and where it's annoying and then turn the volume down, rather than prejudge that.

Having observed a flood of realtime annotations (which was quite exciting) a couple weeks ago on the bitcoin page (https://poloniex.com/) I'd say that it was not overwhelming at all. If two annotations happened to come in together a couple seconds apart I'd not have wanted it to stop updating.

1. Insertion of a new annotations card. This should make space for the card then fade it into view (video).

Great.

1. Insertion of a new reply into a collapsed thread. This should "pulse" the background of the annotation card to indicate updates have been applied (video)

Unless I'm mistaken the video does not seem to show this behavior. The card doesn't have any replies.

1. Insertion of a new reply. This should fade in the annotation much the same as the new card. The entire card color should pulse.

Yes.

1. Insertion of a highlight. I think we should just insert this into the document. If highlights are visible then we can fade them in.

You mean a new annotation whose selection is in the viewport (highlights only work as "only me" visibility now).

For edits I think we can just pulse the card for the moment.

Ok.

For deletions there are two use cases...

1. An entire thread is removed. We should just fade out and remove the card.

Sure.

1. A parent annotation is removed but it still has children. We should update the card content and pulse the background color to indicate a change.

Ok.

Isn't there also the case where a reply that has no children is removed? Or a branch of a thread is resolved or archived in some way (we should probably plan for this)? I assume again we should pulse the card and update.

What happens if an annotation is changed while it is out of view? My thinking is that the transition be suspended until it scrolls into view. Otherwise it would be easy to miss. This might be too difficult for a first pass at this feature though.

You might pulse the up or down arrows on the heatmap. I agree that queueing stuff is probably not sustainable.

What happens if a user is editing or interacting with the sidebar? I'd like to ensure that the view doesn't move around. Ideally if a user is interacting with a card it remains in place. Again not sure how difficult this is. The last thing we want is for someone to be creating an annotation and have the form pushed out of view by new annotations.

Yes. Though what if they're creating a reply and the parent is deleted?

Do we need an indicator of new annotations as they come in? Something like a badge near the search bar?

In addition to all the other visuals? Not sure about that.

I think the other major case that's missed here is what notification we see when the sidebar is closed. We used to have an action where the related tab updated and flashed. I'd like to see that come back.

Another thing: For a new source level annotation, the selection/highlight should probably also flash even if show annotations are turned off, to show where it's anchor is.

[dwhly]

The following assumes low traffic, under say 1 annotation every 30 seconds. Any more than this and we likely want to buffer annotations and show a notification that allows the user to manually trigger the the update, much like Twitter does on it's feed.

I'd support this if the rate was measured over some time (> 5 source level annotations over 30 seconds?) and not two annotations that just happened to come in at approximately the same time. Also, if its a collapsed card w/ the reply count updating that's much less intrusive. I'd probably just let those happen. Generally: Lets tend towards letting realtime happen, and see when and where it's annoying and then turn the volume down, rather than prejudge that.

Having observed a flood of realtime annotations (which was quite exciting) a couple weeks ago on the bitcoin page (https://poloniex.com/) I'd say that it was not overwhelming at all. If two annotations happened to come in together a couple seconds apart I'd not have wanted it to stop updating.

1. Insertion of a new annotations card. This should make space for the card then fade it into view (video).

Great.

1. Insertion of a new reply into a collapsed thread. This should "pulse" the background of the annotation card to indicate updates have been applied (video)

Unless I'm mistaken the video does not seem to show this behavior. The card doesn't have any replies.

1. Insertion of a new reply. This should fade in the annotation much the same as the new card. The entire card color should pulse.

Yes.

1. Insertion of a highlight. I think we should just insert this into the document. If highlights are visible then we can fade them in.

You mean a new annotation whose selection is in the viewport (highlights only work as "only me" visibility now).

For edits I think we can just pulse the card for the moment.

Ok.

For deletions there are two use cases...

1. An entire thread is removed. We should just fade out and remove the card.

Sure.

1. A parent annotation is removed but it still has children. We should update the card content and pulse the background color to indicate a change.

Ok.

Isn't there also the case where a reply that has no children is removed? Or a branch of a thread is resolved or archived in some way (we should probably plan for this)? I assume again we should pulse the card and update.

What happens if an annotation is changed while it is out of view? My thinking is that the transition be suspended until it scrolls into view. Otherwise it would be easy to miss. This might be too difficult for a first pass at this feature though.

You might pulse the up or down arrows on the heatmap. I agree that queueing stuff is probably not sustainable.

What happens if a user is editing or interacting with the sidebar? I'd like to ensure that the view doesn't move around. Ideally if a user is interacting with a card it remains in place. Again not sure how difficult this is. The last thing we want is for someone to be creating an annotation and have the form pushed out of view by new annotations.

Yes. Though what if they're creating a reply and the parent is deleted?

Do we need an indicator of new annotations as they come in? Something like a badge near the search bar?

In addition to all the other visuals? Not sure about that.

I think the other major case that's missed here is what notification we see when the sidebar is closed. We used to have an action where the related tab updated and flashed. I'd like to see that come back.

Another thing: For a new source level annotation, the selection/highlight should probably also flash even if show annotations are turned off, to show where it's anchor is.