Comments & Annotations
- XWiki
- Design
- Idea
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:
- content made as an initial draft, made to gather feedback and be refined
- 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:
It is not in our current Icon theme.
Look
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.
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
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.
Proposal #2.2 | Annotation icon
Current situation: The icon used for annotations is a hard-coded Silk one.
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:
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)
Proposal #3: Show & filter annotations
Current situation
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:
- content made as an initial draft, made to gather feedback and be refined
- 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
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.
Proposal #4: Annotation look
Current situation:
Comparison with comments:
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.
Proposal #5: Comments look
Current annotations & comment
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.