Comment on multiple lines in a diff
What's this issue all about? (Background and context)
Commenting on a range of lines (multi-line comments) is a common desire when feedback relates to more than a single line. It is also a favorite feature of customers who previously used Phabricator, Crucible and the like.
What are the overarching goals for the research?
- Understand how competitors approach the UX of multi-line comments.
- Design and test a prototype to validate discoverability, and usability of the proposed solution. This will allow us to decide where to start building. It should include:
- interaction of leaving multi-line comments
- overlapping multi-line comments
- multi-line comments in combination with multi-line suggestions
What hypotheses and/or assumptions do you have?
- The “drag-release” gesture, used by some competitors, is an intuitive way to start a multi-line comment.
- Written and visual indicators of the comment range allow users to quickly understand which lines the comment refers to.
- Users understand if a line has been removed or added when written as
-11or+11.
What research questions are you trying to answer?
- Which parts of the design are easily understood? And which raise the most questions?
- Is the “drag-release” gesture intuitive?
What persona, persona segment, or customer type experiences the problem most acutely?
What business decisions will be made based on this information?
- We'll scope the first iteration of the multi-line comments feature based on this research.
What, if any, relevant prior research already exists?
- SUS Survey - Q1 FY2021 - Optimizing GitLab - Create: “highlight multiple lines for code reviews. For clarity--a code review comment typically isn't about just one line.”
- Code Review - Notes from User 1, GitLab - April 2019
Who will be leading the research?
@pedroms - Product Designer
What timescales do you have in mind for the research?
1 week
Relevant links (script, prototype, notes, etc.)
- Figma Prototype: https://www.figma.com/proto/t3XACGdol0Gi44Mg0ENIao/Multi-line-comments-ux-research-870?node-id=31%3A1174&viewport=4%2C152%2C0.5&scaling=min-zoom
TODO Checklist
-
Product Designer: Create a prototype. -
Product Designer: Draft the usability testing script. -
Product Designer: Conduct one usability testing session. Amend script if necessary. -
Product Designer: Conduct three remaining usability testing sessions. -
Product Designer: Synthesize the data and identify trends, resulting in findings: https://docs.google.com/spreadsheets/d/1H23lpBHh3gg5ZnfVqW96Us2P2YNx8T-P3XbSzvhcMJY/edit#gid=12 -
UX Researcher: Review findings and provide feedback, if needed. -
Product Designer: Document findings in Dovetail: https://dovetailapp.com/projects/12358fa5-f7c5-4b9f-91f8-d983145c13c6/readme -
UX Researcher: Sense check the documented findings. -
UX Researcher: Update the Solution validationresearch issue. Link to findings in Dovetail. Unmark asconfidentialif applicable. Close issue.
Competition
| Name | Comment | Docs | Screenshot/Video |
|---|---|---|---|
| GitHub | Click-and-drag, scrolls view. Doesn't allow commenting over collapsed regions. Doesn't highlight the comment range when viewing, but indicates range in text at top of comment. Comments are attached to the bottom of the range. | Docs |
Usage Onboarding 
|
| Gerrit | Select a code block or line with mouse or keyboard and press 'c' or click on the popup comment icon. Allows commenting over collapsed regions. Comments are attached to the bottom of the range. Highlights comment range when hovering. | Docs |  |
| Phabricator | Click-and-drag, scrolls view. Comments are attached to the bottom of the range. Highlights comment range when hovering. | Docs |  |
| Crucible | Click-and-drag, scrolls view. Highlights comment range when hovering. | Docs | |
| Review board | Click-and-drag, scrolls view. Allows commenting over collapsed regions. Comments are attached to the top of the range. New comments made on the 1st line of an existing multi-line comment will apply to the whole range of the existing comment. | Docs |  |
| Azure DevOps | Not supported | ||
| Bitbucket | Not supported | ||
| Reviewable | Not supported |
Links / references
Edited by Katherine Okpara