Comments & Annotations

Last modified by Thiago Krieck on 2024/12/17 17:06

Description

General notes (unorganized)

Issue #1: Other than simply exploring and trying stuff, there is no way for a new user to know how to annotate text in XWiki.


Note: When selecting a text in vew mode in XWiki you either want to copy it, annotate it or, you’re presenting and trying to highlight the text to someone while talking.


Issue #2: To see annotations, you have to enable viewing them. I understand that this has been done to avoid distracting the user from the actual content with annotations.

Proposal #2: Analyzing the usecases of annotations and their relation to the content, I believe we should have showing annotations enabled by default. Closing them should be the choice, not seeing them.

Justification:

There are mainly two relevent cases  of content when discussing annotations:

  1. content made as an initial draft, made to gather feedback and be refined
  2. content that reached a final version and is ready to stay in that form in the wik
    • long term content (example: procedures, documentation)
    • short term content (example:weekly overview, tasks, ideas)

In case 1, the author or the person that wants feedback expects a high level of annotations. They want the high level of annotations. Their focus is more on the feedback than the actual content. Annotations are supposed to distract the user from the content, in this case. >>>> show annotations by default

In case 2, the author or the people that worked on that content expect little to no extra feedback. When they revisit that content they do NOT expect to see annotations. Thus, they will NOT think to check the annotations. >>>> show annotations by default.

Examples of this UX pattern: Google Docs (tbh, best for gathering feedback on content and reformulating), Notion, Check if confluence too


Issue #3: An annotation can be made only through keyboard: ctrl + M. There is no button for doing this action.


Bug or Lack of functionality: If 2 people make the same annotations, clicking on the annotation icon will show only the first.


Accessibility/usability issue: The annotation icon has very little clickable area.


Color theme issue: Annotation comment pop-up's shadow uses $theme.linkColor as its color.

Proposal: It should be the same as the dropdown menu's shadow, for consistency reasons.


Issue: The annotation's pop-up can go outside the screen's default width, enabling horizontal scrolling. This scrolling is an additional action that the user has to do to see the whole annotation.

Proposal: The pop-up should stay in the default limits of window.

Implementation idea: On a big screen, depending on the position of the mouse on the screen when clicking on an annotation or creating an annotation, the annotation would open in the right or in the left. By default it should open in the right side, but if the mouse passes the left half of the screen, it would open in the right.


Note to keep in mind: If you respond to an annotation, the annotation will have a View thread link. This doesn’t say how many comments it has.


Issue & idea: There is no way of resolving an annotation like in Google Docs.


Issue: When clicking on the anchor link of an annotation, the user is led to that mention but it is at the beginning of the screen, making it hard to see immediately if he doesn’t already know this pattern.

Proposal: When clicking an anchor link of the annotations, the referenced text should be highlighted for 10 seconds to be easily identifiable.


Idea: Replace the annotation icon with a circle picture of the author of the annotation. This is interesting, but of you have a full page of annotations it will be very distracting to also have pictures.


Issue: You shouldn’t have to click on Filter to see the list of annotation authors. You should just see them.


Issue: When clicking on filter, the existing authors are not already checked, even though all annotations are showcased.


Bug: If the user already opened an annotation dialog and hits Ctrl + M again, it will minimize the window (Mac). It should just close the previous annotation dialog and open another one.


Issue: It’s not obvious that you should click on the annotation icon to close a opened annotation.

Proposal #1: Annotate button inline

Current situation: Select a piece of text and use Ctrl+ M to add annotation.

Issue #1: Other than simply exploring and trying stuff, there is no way for a new user to know how to annotate text in XWiki.

Issue #2: An annotation can be made only through keyboard: ctrl + M. There is no button for doing this action.

Proposal: When selecting a piece of text in view mode, the user can see an icon in upper corner of his selected text.


Improvement details

As said before, when selecting a piece of text in view mode, the user should see an icon in the upper corner of his selected text.

When clicking that specific icon, the user can add an annotation.

The CTRL + M keyboard shortcut is kept as a functionality.

The icon should showcase the idea of adding a mention/note/comment very clearly. The "note" icon in FA is not as clear in that sense, so I would incline to using a comments icon:

1733315582943-597.png

It is not in our current Icon theme.

Look

annotate button.png

Proposal #2.1 | No need for an icon for annotations

Current situation: To view an annotation, you have to click the corner icon of the annotation.

clicking an annnotation.png

Issue: Unfamiliar UX pattern (in most software, annotations do not have a corner icon, you just click the highlighted text) + little clickable area

Proposal: Drop the icon and make the annotated text in content clickable. When clicking the annotated text, the annotation opens.

Look 1

see annotation without icon.png

Look 2 (+ hover effect)

Ideally, we'd also have some visual effect when hovering on a annotation so it's obvious that it's clickable. Also, it differentiates highlighted text from annotated text.

see annotation without icon hover effect.png

Proposal #2.2 |  Annotation icon

Warning

This is an alternative proposal to 2.1 in case 2.1 implies too much difficulty in implementation.

Current situation: The icon used for annotations is a hard-coded Silk one.

1734079541703-461.png

Issue: For any other icon set, this icon breaks iconography cohesion and looks outdated.

Proposal: It should be mapped to our Icon Theme and have an alternative icon in the FA set, at least.


  • It doesn't need to be as clear in its meaning as the icon for adding an annotation because its role is to just signal the existence of something more, not the addition of a certain type of info.
  • It should be simple enough to not clutter the UI.

An icon that could be used is:

1733315556487-694.png

It's not in our current Icon Theme.

Its color could stay similar to the one in the Silk set as it is meant to get attention from the user without it cluttering too much. We could use the warning box's text color (I'm sure there is a color variable, but I can't seem to find it)

new icon annotation.png

Proposal #3: Show & filter annotations

Current situation

current UI for showing annotattions.png

Issues

Issue #1: To see annotations, you have to enable viewing them. I understand that this has been done to avoid distracting the user from the actual content with annotations.

Proposal #1: Analyzing the usecases of annotations and their relation to the content, I believe we should have showing annotations enabled by default. Closing them should be the choice, not seeing them.

Justification

There are mainly two relevent cases  of content when discussing annotations:

  1. content made as an initial draft, made to gather feedback and be refined
  2. content that reached a final version and is ready to stay in that form in the wiki
    • long term content (example: procedures, documentation)
    • short term content (example:weekly overview, tasks, ideas)

In case 1, the author or the person that wants feedback expects a high level of annotations. They want the high level of annotations. Their focus is more on the feedback than the actual content. Annotations are supposed to distract the user from the content, in this case. >>>> show annotations by default

In case 2, the author or the people that worked on that content expect little to no extra feedback. When they revisit that content they do NOT expect to see annotations. Thus, they will NOT think to check the annotations. >>>> show annotations by default.

Examples of this UX pattern: Google Docs (tbh, best for gathering feedback on content and reformulating), Notion

Issue #2: The filtering & disabling/showing annotations Ui doesn't have good visual structure.

Proposal #2: We should improve it. See improvements below.

Improvements

#0 Seeing annotations should be enabled by default.

Disabling and filtering annotations is done from the same menu item (any page> More > Annotate), but the UI is a bit different.

#1 Users are shown one after another horizontally, saving more vertical space between the page title and the content. For lots of user, the list wraps on the next line.

The users are ordered alphabetically by their first name so the author can find a certain person in a long list easily.

#2 For long lists, we should also have a Select all and Unselect all button.

#3 This UI would also have an "x" icon to close it in 1 click. This way the user doesn't have to do 2 clicks and quite a lot of mouse movement to not see this UI component (as it is urrently)

If we have only one line of users

show annotations _   short list.png

If we have more than one line of users

  • The names will wrap on the next line.
  • There will appear the options to select all or unselect all.

show annotations _   long list.png

Proposal #4: Annotation look

Current situation:

clicking an annnotation.png

Comparison with comments:

comaprison.png

Issues:

  • An annotation's space usage can be optimized,
  • its look can be updated to look more modern,
  • the shadow should be the same with any dropdown menu's shadow
  • the profile picture occupies a bit too much space
  • its look is not cohesive with the comments

Improvement:

We simplify the look of an annotation and make it cohesive with the comments.

#1 The profile picture is much smaller, focusing the attention on the text.

#2 We keep the date & time on the same line with the name of the user.

#3 We add a "x" icon to close the annotation in a easier way. Currently, the user has to click the annotation icon to close the annotation.

#4 We add a "Mark as solved" button that when clicked turns an annotation into a simple comment.

"Mark as solved" is a common functionality in many popular software like Google Docs & Notion. Google Docs takes away the highlighting and checks the comment, literally marking it as solved. In Notion, when clicking the check icon, the annotation is completely deleted.

annotation.png

Proposal #5: Comments look

Current annotations & comment

comaprison.png

Issues:

  • outdated look
  • long mouse movement to reach quick actions related to a comment
  • small tappable area on mobile for comment actions

Improvement

#1 We add the "View thread" button that collapses or expands the sub-comments of a comment. On collpase, the chevron is pointing to the right, on expand, it is pointing downwards.

#1.1. Ideally, if not too hard to add, this "View thread" button also has the number of sub-comments of the initial comment. If there are 0 sub-comments, the "view thread" button isn't viewable.

#2 Quotes get a new look, with a big quote at the beginning, followed by big italic link-colored text.

#3 Comment actions get added below the comment content, with labels.

Note: Annotations should have their look updated to be cohesive with comments.

comments.png


 

Get Connected