Comments: UX exploration for quick reply and other actions

[laurentlb]

Hi,

Our UX team at Google explored how to add expose actions to the Commenting mechanism. I'm copying below their doc.

---

With the goal to improve discoverability and to promote certain actions on comment threads to be similarly prominent as "Reply" (e.g. for quick actions like "mark this thread as resolved with a canned reply, or viewing a suggested edit), we are proposing a feature that helps us to achieve this goal.

Part 1

The flow starts with an “Unresolved” comment from a reviewer. The current user is assumed to be the author of the change / pull request, who will generally not leave very lengthy comment replies, but instead address suggestions in code and mark the thread as resolved with a standard reply like “Done.” for the reviewer to take another look. “Reply” button will be a split button that displays secondary actions. The goal to place these secondary buttons here is to help users to take actions without opening the “reply” textarea.

Also, we want to display a “context menu” (3 dots menu) next to the buttons located on the right top corner from each comment. There users can find actions related to the comment like “Resolve and save”. Adding this menu will give us the flexibility to offer more actions to users without overloading the UI.

Since multiple code review tools have the ability to attach a suggested fix, the "Show Edit" button could be added by VS Code, with a new API. This would be very useful because this action should be easily discoverable (since it's not attached to every comment, users may not search for it in a submenu) - it could be on the same level as Reply.

Part 2

This proposal is an upgrade from the previous one. Unresolved comments allows users to “Reply”, “Resolve the comment or View edit” (We will display 2 buttons maximum, those buttons change depending on the context of the comment). If a user opens the reply text area, we offer assistive chips with quick replies. This proposal can scale to add new functionality. E.g. automated responses based on context.

From a Technical point of view: We need a mechanism to say "this action is like a reply". I think we might be able to introduce a new magic value for the group property in menu contributions to achieve this: https://code.visualstudio.com/api/references/contribution-points#contributes.menus. Alternatively we could create a new menu contribution point, instead of comments/commentThread/context it could be comments/commentThread/inline or something.

Commands affecting a comment thread in VS Code can currently be contributed to two menus: comments/commentThread/title and comments/commentThread/context. The commands for title are shown as icons in the top right corner of the comment thread widget, the commands for context are shown as buttons while the user is typing a reply.

In our case, the quick actions described above should be available to users without having to start typing a reply, so they are contributed to the title menu. To promote some of them to buttons next to “Reply …” or as “reply-like” actions in the overflow menu of a split “Reply” button, they should ideally be distinguished from other commands contributed to the title menu, which should not get the same visual treatment, e.g. because they are secondary actions performed only infrequently by users.

The group property on menu items currently supports a special navigation value. It might be an option to introduce a new magic value here to mark “reply-like” commands.

Another approach might be to define a new menu to contribute commands to, like comments/commentThread/quickActions.

[alexr00]

@laurentlb thank you for all the details about how these flows work. It's helpful to understand how the various parts world work together.

Here are the individual feature requests that I see here:

• Always visible buttons at the bottom of the comment thread
  • Some of these buttons are "reply-like" and open the reply input.
• A way to add "quick" replies when the reply input is open.

This one should already be possible for you to do with submenus:

• A "..." menu in the comment thread title.

[alexr00]

@daviddossett I would be interested in hearing your thoughts on this!

[daviddossett]

Some quick early feedback:

• I think it's a good idea to expose the option to resolve a thread without commenting.
• I think we should keep the reply text area in some form. Replacing it with a button adds a click and the secondary actions in the split button make it feel heavier than it is.

I think GH has handled this well by showing the resolve action below the reply input. As a user I know I can resolve without commenting and I don't need to go menu diving to find it.

• Does "Mark as Done" === resolve? We should be consistent with the terminology if possible.
• Wasn't sure how "Mark as Acknowledged" would work. Is this a concept on GH or somewhere else?
• On part 2, I think it's somewhat strange to have to hit "Reply" to expose actions to resolve etc. More clicks.
• Would be good to see an e2e flow for what you have in mind re: "Show edit".

[laurentlb]

Does "Mark as Done" === resolve? We should be consistent with the terminology if possible.

This command is defined by the extension. In our extension, the mark as done command adds a new comment (with just the word "Done") and resolves the discussion. Note that it overlaps with the concept of quick replies. In a GitHub extension, the command would be slightly different.

Wasn't sure how "Mark as Acknowledged" would work

Again, it's an extension-defined command. You can ignore the details.

I think it's somewhat strange to have to hit "Reply" to expose actions to resolve etc.

I agree with that; I'll be happy to see alternative designs.

[hermannloose]

@alexr00

Some of these buttons are "reply-like" and open the reply input.

I think there was some confusion here (and I apologize for my verbosity under "Technical point of view"):

We would like to have "reply-like" actions / quick replies that should not open the reply input, because they would post a canned message like "Done." or "Acknowledged." to save the user time, but they should ideally be discoverable near where the user would otherwise manually reply, as opposed to being very hidden in an overflow menu.

We currently contribute these kinds of actions to comments/commentThread/title but the icon-only buttons with their very small click targets cause friction for our users as they require precision. See also https://github.com/microsoft/vscode/issues/150824#issuecomment-1149779931 on this issue in general.

These quick reply actions should be commands, because different quick replies would differently affect thread resolved state (and possibly extension-specific internal state not relevant to the Comments API). I want to preemptively stress that point to avoid a direction where quick replies / canned replies might be modeled as strings that the extension can provide on a thread.

I think for clarity, let's stick with this primary notion:

Always visible buttons at the bottom of the comment thread

The "reply-like" angle was mainly to explain that some of these buttons have a conceptual link with the "Reply" button, whereas something like "Show edit" is completely different from replying, but ideally we would like to place it in a similar location. If buttons had to move into an overflow menu / split button next to "Reply" due to space constraints, the "reply-like" actions would be good candidates, whereas "Show edit" would not be.

I think we don't have a very strong opinion on whether the actions for these buttons should be contributed to:

• comments/commentThread/title with a magic group value to display them next to the "Reply" button
• a new menu contribution point like comments/commentThread/inline or comments/commentThread/quickActions

The second option sounds cleaner to me.

A way to add "quick" replies when the reply input is open.

The ability to offer quick replies while the reply input is open would also be interesting and separate, but I think from our side less important than the one-click quick reply option.

@daviddossett

I think we should keep the reply text area in some form. Replacing it with a button adds a click and the secondary actions in the split button make it feel heavier than it is.

The reply text area is technically already a button, it's just styled like a text area so it appears to expand. There would be no extra click for a normal reply, but secondary actions in the split button would require two clicks to access quick replies.

Personally, I would prefer quick replies as their own buttons similar to the "Show edit" button in the mocks above (and this is how our code review UI handles it), but we have to consider what happens when the number of quick replies is a bit larger. Something like "Reply" (the native one), "Done", "Acknowledged" and "Show edit" can quickly clutter the space.

[alexr00]

@hermannloose, now that we have the always visible additional actions buttons, is there still a need for more rows of buttons for quick replies?

[vscodenpa]

This issue has been closed automatically because it needs more information and has not had recent activity. See also our issue reporting guidelines.

Happy Coding!