Considerations for annotation & comments

[krusynth]

There are several weaknesses with the current annotation & commenting design:

• Discussion tab isn't found by most users.
• Users do not have an easy way to ask questions directly (probably due to the above item).
• Annotation is a confusing word.
• The current annotation process is not intuitive or expected.
• Annotations are hidden by default, so it's impossible to see the actual discussion.

We should use this thread to discuss potential solutions, but we need a total UX overhaul here.

Here are a few ideas I've thought of:

• Always show the annotations, perhaps collapse some of the content. (How does this work on mobile?)
• Don't require users to select-to-annotate - use some sort of annotation link/icon instead. Maybe this is per-paragraph, off to the side where the current annotation icon is. (We could eliminate Annotator altogether this way.)
• Change the annotation process to make the suggesting vs commenting process more clear.
• Move or eliminate the discussion tab.
• Allow some sort of prominent FAQ area, or perhaps allow admins to flag comments/annotations to include in this?
• Allow some sort of summary/alternative content. Many of our documents are in legalese, and many of our users are unable to understand them well.

[sethetter]

Per a discussion earlier about implementation considerations on the client side going forward -- if we are going to be rethinking the UX on the document page quite a bit, it would be a good time to consider technology choices there.

There's been talk about moving to server side rendering, which I think is completely logical for the majority of our application. The one place that still needs high level of JavaScript help to really get the UX right is the document engagement page.

For just a single page, we wouldn't need to use a full-featured framework such as Angular 1 or 2, or Ember either for that matter. I'm thinking it would be best to consider something more minimal such as React or Vue.js. I'm going to dig in on these and see which one appears that it will best fit our needs.

Regardless of which choice we make, I would strongly urge us to use this opportunity to move away from Angular1. If a large amount of the code for the most interactive piece of our application is about to change, now would be the time to do it.

[krusynth]

Personally, I would like to avoid many of the current hoops we have to jump through as a result of the Javascript-only frontend. (Notably social links, among many, many others.)

In my ideal world, the entire page would be compiled and delivered by the server - it's not that much content - and dynamic elements only swapped when the state is changed. We don't need two-way binding or persistent polling of any of the data on this page - only to update when the user does one of the three (or so) actions available here. This also allows us to cache the entire page at the server level (via Varnish/Nginx/etc) which would be much better for performance too. Anything heavier than a simple Ajax request on this page seems like massive overkill and resource-hogging to me. (We will, however, eventually need polling for #1010 - but not two-way binding still.)

But that's just, like, my opinion, man.

[sethetter]

Went through all the issues today to try and find anything related to document page UX, here's a rough list:

• Comment & Annotation permalink-link is hidden when comments are disabled #1025 - permalink hidden when comments disabled
• Allow document authors to add comments even if the document is closed for comments. #1022 - allow sponsor comments when disabled
• Reconsider font choices #1016 - font choices
• A way to see that documents are unpublished or in draft on the front end #998 - show as unpublished/draft on front end
• If comments are closed, change messaging #992 - change messaging if comments closed
• Interface for "discussion as" group or individual #922/1024 - "discussion as" workflow
• Better tools for anti-harassment #920 - anti-harassment tools
• Sidebar links do not appear for annotations made on preformatted text #853 - sidebar links not appearing for annotations on preformatted text
• Document pages open at ~half page width (iphone, safari) #849 - doc page opens at 1/2 width on mobile
• Support footnotes in documents #833 - footnotes in documents
• Support for very large documents #832 - very large document support
• Annotation side-link sometimes becomes misaligned with relevant section #822 - annotation side-link sometimes misaligned
• Alignment inconsistencies across pages #810 - mobile annotations
• Consider ways to make Discussion tab more prominent #806 - discussion (comments) tab not prominent enough
• Hovering problematic when multiple superimposed edits/annotations #796 - hovering problematic with multiple notes
• Can submit empty annotations/replies through the tooltip window #792 - submit empty replies, annotator
• Difficult to distinguish annotation from edit in sidebar #791 - difficult to distinguish edit / note
• Allow visitors to view and scroll through all annotations for a document #790 - easily browse all annotations on a document
• Clicking the currently-opened annotation anchor should close the sidebar. #780 - close sidebar by clicking current open annotation
• Can't unlike/unflag a comment #778 - can't unlike/unflag
• Annotation sidebar must be closed to click on other comments  #777 - must close sidebar to view other comments
• Mobile interface issues #776 - mobile interface issues
• Reply on yourself doesn't refresh #671 - reply on yourself doesn't refresh
• Don't show "Sponsored by" if we don't have the name of the Sponsor. #670 - don't show sponsored by if we don't have name
• Table of contents label is too small #669 - table of contents label is too small
• Adding annotations doesn't update side numbers. #628 - new annotations don't update sidebar numbers
• Table on Contents sidebar sometimes overlaps with text #617 - table of contents text overlap
• Need loading indicators #602 - loading indicators
• Add a "send" button in the comments section for more intuitive commenting #549 - "send" button for intuitive commenting
• Page Jumping Around #472 - page jumping around
• Add easy cross references between annotations #200 - cross reference annotations
• Add annotation social shares #195 - filter activity by user role
• Add Annotator touch plugin #128 - annotator touch
• Deleting Annotations #122 - deleting annotations

Also, regarding the possibility of switching front end technology choices, these issues could/would be addressed:

• Clean up and normalize angular naming conventions #937 - angular naming conventions
• Move site title in Angular global to use locale file instead #763 - site title controlled by angular
• Explore ES6 usage #696 - explore es6 usage

There could very well be more, feel free to add!

[krusynth]

The good news is, that's almost 10% of our open issues! So if we do this right we can put a big dent in things.

[sethetter]

Closing this due to UX overhaul in v4.