UI for commenting/annotating documents

[tkrieck]

Hey everyone, here’s a proposal for the commenting UI for Cristal. It follows the basic flow of XWiki Standard, with a few improvements.

Comment area with a single entry

Anatomy of the Comment Component

Each comment consists of several elements:

• User Avatar: Displays the profile image of the commenter.
• User Name: Shows the name of the user who made the comment.
• Date and Time: Indicates when the comment was posted.
  • Edits should appear between parenthesis after the original date
• Comment Content: The text of the comment itself.
• Action Bar: Displays different actions a user can take, depending on their permissions. These actions may include:
  • Reply
  • Edit
  • Share: This replaces the previous “link” action but functions the same way.
    • This might a personal bias, but I feel that, these days, the action “sharing” is more recognizable as an action that gives the user a link to be shared elsewhere that points to the intended location (a comment in our case)
  • Delete

Basic elements of a comment

Behavior of the Commenting System

• Initial State: The commenting area will appear below the document and will be empty initially.

---

Empty State

---

• Add New Comment: Logged-in users with the appropriate permissions will see an “Add new comment” input at the top of the commenting list.

  • Clicking this input opens the comment component into editing/adding mode:
    • A formatting toolbar becomes visible.
    • The text area expands.
    • Confirm and Cancel buttons appear.
  • After submitting a comment, the system will revert to the default “Add new comment” state.

User adding a new comment:

---

• Editing Comments: If a user has permission to edit their own comment, the comment will reopen (in place) in edit mode:

  • The comment’s content will be pre-filled in the expanded text area.
  • The formatting toolbar reappears.
  • The action bar will be replaced by Save Edit and Cancel options.

Editing comment UI changes

---

Thread Line

The thread line helps visually guide users through comment threads and nested replies. As an UI element it was heavily inspired by the comments section of Reddit.

Thread line example

• The thread line appears when there are:

  • Nested comments (replies) under the current comment,
    AND
  • Sibling comments directly following the current comment.

• The thread line serves two purposes:

  1. It indicates that more comments are available below the current comment.
  2. It helps users visually follow the progression of a comment thread, showing where the current thread ends and a new one starts.

• Thread Line Visibility:

  • If there are no comments directly below the current one, even if it has nested replies, the thread line will not be displayed.
  • If all comments are siblings without any nesting, the thread line will also remain hidden.

Visualization of the thread line on multiple comments (on of the comments is in edit mode)

No thread line is visible on single comments and no nesting

As you can see, the basic behavior of the comment section is not that different from XWiki Standard or other commenting systems.

So, to conclude, I would like your opinions about this proposal as a whole but especially what do you think of:

• Having the “new comment” input always visible (but reduced in size) instead of a button
• Applying a thread line instead of just indenting each nested comment
• Using the “share” sematincs instead of “link”

As always, thank you all for reading.

---

Edit: As I commented below to @mleduc , here is a basic annotating flow for these screens.

Selecting text for annotating
Cursor over the annotate button on the toolbar:

Annotating popover

Annotation marker

Selected annotation, with action to go to the full comment.

Full annotation
When navigating from the annotation itself (via the "Full comment"version) the background is in a yellowish shade serves to indicate to the user what is the annotated comment in case there’s a lot of them.

Edit 2:
No threaded comments
In case we don’t go the thread line comments, like above, here an example of the comment section flattened, with replies and quotes. The quote syntax is just an example that I took from Discuss as an example.

[mleduc]

Thanks for working on this.

I think this proposal is presenting some limitations that are important to discuss:

• I don’t see anything related to annotations in this proposal. How do we see the selected text of an annotation. How are user able to easily navigate between selected text and comments, etc.
• While the threaded UI looks nice, I feel like this is just a variation on the tree-based comments structure we already have on XWIki. I think it would be interesting to think of a way to flatten the messages while keeping track of which message is a reply to which. For instance what discuss is doing. One of the main pro of flattening thing is that it would also allow to introduce pagination on comments which we are missing on XWiki currently.
• Also, having the comment in a tab at the bottom is also not optimal as it does not allow users to both see the comments/annotations along with the text. This is why I think it would be useful to have weight pros and cons with the approach proposed by many knowledge managements software, with comments in an expandable right column (see screenshot below from outline, but it’s the same of others).

I know the points I raised above are not easy to answer, especially taking XWiki’s compatibility into account. Also, they are good question to answer for XWiki itself.
The rest of the proposal looks good!

@tkrieck

Having the “new comment” input always visible (but reduced in size) instead of a button

+1

@tkrieck

Applying a thread line instead of just indenting each nested comment

See my comments above.

@tkrieck

Using the “share” sematincs instead of “link”

+1

Annex screeshot

[CharpentierLucas]

Hello!
Quick comment: Do you have a strategy for guest users / not logged in users?
In XWiki the UI for message gets a bit complex because plenty of strategies have been implemented for Admins to choose from. I think it’d be interesting to know what this UI would look like for a logged out user, assuming they can even see anything. The simple strategy that you might want to use at first is just assume that they won’t get here :D.

I hope this interrogation isn’t too off topic ^^`

Lucas C.

[tkrieck]

@CharpentierLucas

I hope this interrogation isn’t too off topic ^^`

It is not, don’t worry. From my POV the UI will be exactly the same, except the action buttons will be removed. And if the permissions are set accordingly, the whole tab can be hidden.

@mleduc

I don’t see anything related to annotations in this proposal. How do we see the selected text of an annotation. How are user able to easily navigate between selected text and comments, etc.

It was not in MVP, so I didn’t give it much priority, but you can check the updated proposal.

@mleduc

While the threaded UI looks nice, I feel like this is just a variation on the tree-based comments structure we already have on XWIki.

And you are not wrong, it is a modification on it just with better visual cues.

@mleduc

I think it would be interesting to think of a way to flatten the messages while keeping track of which message is a reply to which. For instance what discuss is doing.

We could go this way. The thing with this approach, at least from my POV, is to keep track of different threads that can happen naturally in a discussion. This is a difficulty I have with Discuss as well, mind you. Sometimes the discussion go on 3 different topics, and it’s hard to keep everything in mind if everyone is not very diligent with their quoted replies.

@mleduc

One of the main pro of flattening thing is that it would also allow to introduce pagination on comments which we are missing on XWiki currently.

Was this featured missed from XWiki at some point? If it was, then maybe is a good point to go in this direction.

@mleduc

Also, having the comment in a tab at the bottom is also not optimal as it does not allow users to both see the comments/annotations along with the text. This is why I think it would be useful to have weight pros and cons with the approach proposed by many knowledge managements software, with comments in an expandable right column (see screenshot below from outline, but it’s the same of others).

I agree on the sidebar / bottom bar, it was my initial proposal months ago. But it can be a problem when a content related right sidebar is present. You can follow prior discussions on it here

[mleduc]

The for update the proposal @tkrieck !

@tkrieck

It was not in MVP, so I didn’t give it much priority, but you can check the updated proposal.

For sure, we mainly need to make sure that the comments design will not prevent us from adding annotations later.

@tkrieck

We could go this way. The thing with this approach, at least from my POV, is to keep track of different threads that can happen naturally in a discussion. This is a difficulty I have with Discuss as well, mind you. Sometimes the discussion go on 3 different topics, and it’s hard to keep everything in mind if everyone is not very diligent with their quoted replies.

Good point. So we’ll need to weight in:

• ease of following threads (I don’t have trouble myself, but I get your point)
• pagination

I’m +1 for “flat” and +0 for “tree”.

@tkrieck

Was this featured missed from XWiki at some point? If it was, then maybe is a good point to go in this direction.

Related issue: Loading...
Actually, regarding this topic, I think there are two different aspects:

1. scaling: we shouldn’t load 100% of the messages
2. pagination: we should only present a selected set of messages at once

Scaling can be solved easily for both flat and tree, for flat by pagination, for tree by adding “load more” buttons at relevant places.
Pagination is only relevant for flat, so if we go with tree we can ignore it.

@tkrieck

I agree on the sidebar / bottom bar, it was my initial proposal months ago. But it can be a problem when a content related right sidebar is present. You can follow prior discussions on it here

Good point, thanks for the pointer. In this case we can go with the design close to XWiki’s one that you added to the initial proposal.

Some more questions regarding the updated proposal for annotations.

@tkrieck

Annotating popover

Does this mean we’ll need to introduce a “small” editor to fit this more limited space of the annotation popup?
I can’t find an issue, but I know the same was discussed for XWiki, where it would be interesting to have a more compact rich editor for the UIs.

@tkrieck

Annotation marker

Looks good. I’m just wondering about accessibility (cc @CharpentierLucas). The contrast is probably a little low with between the highlight yellow color and the white background. But with the additional underline I guess it’s fine.

[tkrieck]

@mleduc

Good point. So we’ll need to weight in:

• ease of following threads (I don’t have trouble myself, but I get your point)
• pagination

I’m +1 for “flat” and +0 for “tree”.

I will make a proposal with a flat layout as well, in case we go with this solution.

@mleduc

Does this mean we’ll need to introduce a “small” editor to fit this more limited space of the annotation popup?
I can’t find an issue, but I know the same was discussed for XWiki, where it would be interesting to have a more compact rich editor for the UIs.

Yes, that would be ideal. It does not need to be as full featured as the main one (no macros, for example). A small editor with basic styling capabilities would be enough.

Edit: I made a section on the main proposal with the comments flatened so people can vote more easily.