Option to comment on a notebook AND a PR is confusing

[zaneselvans]

Frequently when I ask someone to comment on a notebook in a PR, they end up commenting on the notebook itself as a file, not as part of the PR, so their comments don't show up in the PR conversation / resolution. Having the link to the file and the link to the notebook in the PR be right next to each other and basically identical makes it hard for anyone to know what they're doing.

If someone comes to a notebook in ReviewNB from a PR, I think you should presume they want to comment on the PR, and make sure that's where their comments end up unless they go out of their way to find the file instead.

Relatedly, it would be nice if there was some way to move comments from the file to the PR, rather than needing to ask someone to cut-and-paste them all over again to integrate them into the PR conversation.

My most recent example of this happening.

The Notebook button is just begging to be clicked on, unlike the filename:

[amit1rrr]

@zaneselvans Thank you for opening this discussion. I can see how the current UI can be confusing for a new User.

If someone comes to a notebook in ReviewNB from a PR, I think you should presume they want to comment on the PR, and make sure that's where their comments end up unless they go out of their way to find the file instead.

Right, this is fair. We've a button hint on Notebook button hover that says View Standalone Notebook but that's probably not enough.

It's a question of how to change the UI so it's obvious to user what they're doing (Viewing PR diff vs. Opening a Standalone notebook file).

Some ideas off the top of my head are -

• Simply right aligning the Notebook button (so that it's away from the file name)
• Changing the Notebook button text to something more explicit
• Making 2 separate buttons ("View Diff", "View Notebook")

If you've any other ideas on how to make this choice more obvious to the User in the UI, please feel free to share those.

Thanks again for writing in with your suggestion.

[zaneselvans]

It's not clear to me what "View Standalone Notebook" means in this context. And it's not clear that the choice of actions to take is between viewing the diff in the PR and viewing the notebook as a file in the repo (not as part of the PR) or that the way one makes this choice is between clicking on the path (which it turns out is a link... who knew?) and the button (which is by far the most obvious thing to click on).

So I think 2 things are needed:

• Make it obvious that the user faces a choice (if you absolutely must present the option to view the whole file even though this is a PR).
• Make it clear what the two options are (comment on the PR, or comment on the full file in a way that will never show up in the PR).

Maybe it's just my use-case, but in the context of knowing the user came here from a PR, I don't know when they would ever want to go to the full file, and comment on it in a way that is completely detached from the PR itself. And unfortunately that currently seems to be the path of least resistance.

[amit1rrr]

Maybe it's just my use-case, but in the context of knowing the user came here from a PR, I don't know when they would ever want to go to the full file

Usually to look at historical changes to this specific notebook & any past discussion that might have happened on the standalone file.

It's not clear to me what "View Standalone Notebook" means in this context

Can you suggest better wording that would make it more obvious / clearer? It's currently inspired by "View File" option on GitHub PR page.

[zaneselvans]

I think mirroring the GitHub language as closely as possible would be helpful, since that's something pretty much all users will already have familiarity with. "View Standalone Notebook" didn't echo "View File" for me. Is there a reason not to simply say "View File" here too? Users will know it's a notebook already.

[amit1rrr]

We've deployed some UX changes to make these choices more explicit. Specifically,

• We now have "History" button to show past commits of a given notebook
• Both "History" & "Notebook" buttons are right aligned to show that they are separate set of actions than viewing PR diff for that particular notebook file.
• "History" & "Notebook" buttons now have Black color so they're on the same level of fidelity as the file name which opens the diff.
• Tooltip for "Notebook" button now says View standalone Notebook (without diff) to be more explicit

Here's how the UI looks now -

Feel free to suggest additional improvements.

[zaneselvans]

To me, visually, at first this still seems like the buttons are the options I have to choose from, and it's unclear that the link is a 3rd choice. Coming here from a PR for the first time I think I would probably click on Notebook.

At least a tooltip on the link that says "Comment on pull request" or something else indicating that that's where you go to comment on the PR would be helpful. I think it should explicitly say PR or "pull request" and not just "diff" since there are many contexts in which diffs arise.

[amit1rrr]

To me, visually, at first this still seems like the buttons are the options I have to choose from, and it's unclear that the link is a 3rd choice. Coming here from a PR for the first time I think I would probably click on Notebook.

hmm, that might be true from an initial glance but as people hover over, the change of color & cursor should make it obvious that the entire bar is clickable. See screenshot below.

At this point, our best path forward would be to monitor the current change & see how many people end up opening / not opening the PR diff. Based on the data, we can consider further changes if required.

Thank you again for all your help in bringing this to our notice.

[amit1rrr]

To reduce the confusion - we've also added this placeholder text to the comment editor on a standalone notebooks. Please see screenshot.