Let’s talk about Observable Suggestions

We don’t currently have an action for showing resolved comments, but we’re planning on adding it soon.

1 Like

After a few comments… it surprised me each time I made a comment on someone’s notebook, and ended up with a fork where no code had been changed. I have to keep in mind that I want to trash it only after the comment was processed. Am I using it correctly? Do I really need a fork if I just want to send a remark or question, with no code change?

I’m kind of missing a way to say “thank you” to people who sent helpful suggestions and edits (speaking of which, @Fil, thanks for the bit of proofreading on my last notebook)

Based on the last section of the notebok I figure that the Observable team has already seen Evan Czaplicki’s musings on the topic, but sharing it just in case:

1 Like

An “only you will see this” is rather absolute and doesn’t communicate this. Although I can imagine “only you will see this until you click Suggest” is also confusing since the button is not visible until the first comment.

1 Like

I’m afraid that, at the moment, you do. In this first version of comments and suggestions — comments are attached to the notebook itself, and you don’t have permission to leave unsolicited comments directly on someone else’s notebook. Instead the flow is to fork your own copy with your comments, and give them explicit permission to comment on yours instead, by sending it to them as a suggestion. So the discussion occurs on the notebook of the person who initiated the conversation, not the person responding to it.

It’s a sort of “the author is the master of their domain” model.

Thanks for all of the helpful feedback in this thread! As we go back to revisit the design and improve these collaboration features — it’s honestly really quite useful to hear from you all which parts feel weird and which design choices are working and aren’t, because it helps solidify or reverse earlier debates about how the puzzle pieces should be fit together.

1 Like

To add to Jeremy’s reply, yes, because we don’t currently distinguish between comment-only suggestions and suggestions that propose changes to code. And since comments are private (between the suggester and recipient), the fork exists as a home for that discussion.

We’re listening to feedback and reflecting on improvements to the workflow. Also, we’d like to improve how shared/suggested notebooks appear on your profile (see Feature Request: Unlist a shared notebook) to reduce clutter, and more generally to offer ways to better organize and find your notebooks.

Thank you for the replies. Jeremy and Mike made clear the need for a fork to hold that specific discussion.

A bit more feedback on the interface/workflow/cognitive difficulties I still see in trying to run the whole process with two accounts:

Lets say that as @fil I’m working on @a_person’s notebook and start with an intent to comment. I click “comment” (I don’t fork).

Step 1 typing comments

While I’m typing I see this message “Suggest to share this with a_person”. It’s not clear what I should to, because typing my comment is what I understand as “suggesting”, so it looks like I’m doing just that. The message disappears when I validate the comment => I’m tempted to read this as “OK this suggestion has been shared now”, but no, it was a comment, not a suggestion, and it hasn’t been sent.

Worse, if I leave the page, the comments are lost.

It all makes sense once you understand that you don’t own the notebook and will lose everything if you play with it just like if you played with the code. But the whole interaction has lead me to think I had commented (as on a normal forum board such as talk.observable).

(Maybe a test on window.close that would remind you that you’re going to lose your changes would help here?)

Step 2: the suggest button.

Send suggestion

[Brief description of changes…]

@a_person will be notified and allowed to comment.

The notebook will be visible to anyone with the link.

“[Brief description of changes…]”

If there are no changes, I have nothing to describe. Again, my comments are not mentioned: that interaction seems to tell me that this is only if I need to send “changes”? => maybe change the wording to [Brief description of changes and comments…]

If my comment is already brief, I have to type it again => maybe pre-fill with the first 200 chars of the first comment?

@a_person will be notified and allowed to comment.” + “The notebook will be visible to anyone with the link.”

I understand that the notebook is “shared to anyone has the link” + “@a_person will receive the link” + “@a_person will be allowed to view and add comments”.

In short, the authorizations regime on comments is different from that on shared notebooks, but in that step they are mixed up, and it’s not obvious why it’s necessary and makes it cognitively difficult to parse.

Step 3: suggestion sent

The notebook reloads as a new SHARED fork in a compare mode. (Again: why SHARED, I just need to share it with @a_person, it should be in a way independent from the notion of sharing… what happens if I unshare… etc.)

@fil suggests merging this: “a question””.

I’m just sending a comment, so all this interface’s widgets don’t really talk to me: “Comparing notebooks”, “diff/base/target”.

I have no feedback on the fact that @a_person has been notified and invited to the discussion I’ve just opened. I have no idea what happens if I close the suggestion before they visit the link from their email. I have no idea that I will receive email notification(s?) when @a_person comments, resolves and/or merges the suggestions.

Step 4: suggestion received

I am now @a_person. I have received this email, I click on the link to the fork/compare page, and the interface tells me to merge if I like what I see. Remember it’s just a comment, so merge should not do anything(then why tell me to merge?) or will it merge the comment in(?).

No way to know except to try. Answer is: it doesn’t merge anything into the original notebook, but sends a notification to the commenter (@fil) that @a_person has merged their suggestion.

Back to the forked notebook, there is a message at the top saying (rightly) that the suggestion has been merged. Good. But the whole conversation has disappeared, on both screens (@fil’s and @a_person’s) (danger!!).


Also unclear: except from my notification emails, is there a way to list “open suggestions on my notebooks”? [EDIT: just saw the tab in my notebooks]


Sorry for the long comment. I think it helped me learn how the system works so I won’t be surprised next time I use it. I’ve tried to outline the parts I didn’t find intuitive or that seemed tricky, but for the record let’s say that in general it works out ok :slight_smile:

3 Likes

Top-notch feedback. Thank you, Philippe!

I have just commented on then closed (without merging) a suggestion I received from @severo; I have no idea if he received my comment (in which I explained why I was closing w/o merging). (Fortunately we have a back channel so, no harm done).

Yes, I received two mails: “Fil commented…” and “Fil (@fil) has closed a suggestion…”. But I understand the problem is that you didn’t have that feedback in the interface.

I generally like the idea. (Great work folks!)

It seems to work well for typo fixes, minor suggestions, etc., which is probably the primary goal.

I do wonder a bit though about how future-accessible the comment discussions will be. Seems like it might still be best to handle more major feedback/collaboration out of band (e.g. on this forum or email).

I don’t see how I can reply to a suggestion? Someone has suggested changed to my notebook, but I actually forked someone else’s notebook and I and to communicate this to the suggester. I don’t see how to do this.

The easiest way would be to comment on the suggestion directly, like so (before closing it):

Does that help?

Yes, it does. thanks

Still getting bitten (or almost bitten) by this UI issue: the “resolve” button is just under the mouse and makes an irreversible action of disappearing the thread. I wish we had something more fool-proof (or @fil-proof :tired_face:).

4 Likes

I’d like the option to add a comment directly to a notebook. Right now, in order to only comment on a notebook I have to attach that comment to an arbitrary cell, even if the comment has no relation to the cell’s content.

1 Like

We’re going to revisit the commenting and suggesting workflow, but I don’t have a specific timeline I can share yet.

We agree that it should be easier to comment directly on anyone’s notebook. Not to make excuses, but the reason for the current design is that we wanted to provide a private space for discussion (so that the author could reply privately, and multiple comments be made simultaneously, hence a fork), and the ability for a comment to be turned into a code suggestion without losing the previous discussion. But I suspect we can find a way to support those cases while still having a lightweight way to comment.

2 Likes

I do like the private space for discussion aspect.

One problem though is needing to make an explicit fork; most of the time I don’t want these “polluting” my list of notebooks, just to make a one-line comment. As a result I am tempted to delete the fork after the author has seen my comment, which ends up eliminating the discussion.

4 Likes

I feel like I’m missing something, but is there a way to reply to someone’s suggestion without either merging or closing it? I’ve received a suggestion that will take a little bit of time for me to review, and I want to acknowledge the person’s contribution and explain why I’m not dealing with it right away. I’ve commented on the first changed cell in their fork, but I don’t know if the comment was actually sent, or if it’s just sitting there waiting until I merge or close the suggestion.

Comments in suggestions are sent as soon as you click the Comment button (along with an email notification), assuming you are the recipient (or author) of the suggestion, so no need to merge or close if you just want to send a comment.