Let’s talk about Observable Suggestions

Site Feedback
1

Today (happy Valentine’s Day, everyone) we launched Observable Suggestions: our take on the pull request, and a way to achieve considerate collaboration across notebooks:

There are some things here that work a little differently than tools you might have used for notebooks before: the conversation lives on the notebook itself, next to live code, not outside of it; private by default; you can suggest directly from someone else’s notebook, and so on…

Let us know if you find any bugs, or have any helpful suggestions for improvement.

(Speaking for myself, I’m pretty excited to start receiving suggestions for the Input Bazaar, for one.)

8 Likes
2

Super excited! Great job!

1 Like
3

Neat! I’ve just made a suggestion to the inputs notebook :slight_smile:

1 Like
4

Reviewed, merged and republished. Thanks @bgchen!

5

That was fast!

I’ve got a question: if I make a fork and then add comments to it, the comment window says “only you will see this” – if I then make a suggestion using this fork, will the original author see those comments?

6

Correct. When you start by working on your own fork, we don’t yet know that you’re intending to suggest it, and only you can see the comments at that point.

When you suggest, it automatically shares the notebook (if not already shared or published), and allows the recipient of the suggestion to see and reply to your comments on the suggested notebook.

1 Like
7

Oh, this is great! :heart:

@jashkenas Something minor I’ve noticed: When switching between the Base/Diff/Target states of a single cell, the cell might not execute correctly due to missing dependencies. Is this something that can be fixed (at some point)?

8

Yes, potentially. We’ve started with simple with per-cell toggling (Or you can toggle every cell in the notebook at once, by clicking the gear in the compare header). But because we know the upstream inputs for each cell, you could imagine an alternative version that would cause the cell to also toggle all of its inputs (and their inputs, and so on) back to the corresponding base/target state.

One reason not to do this by default is that often the purpose of toggling a cell is to show how it would behave in the context of the other notebook: e.g. Yesterday’s formatting function applied to today’s chart.

Ultimately, it would be a somewhat advanced feature — and really the biggest problem with it is finding a clear, intuitive UI for toggling a cell (and all of its inputs) at once.

4 Likes
9

That’s a very good point that I hadn’t even considered.

Perhaps a chain symbol beside a cell’s state selector that can be toggled? Edit: I guess it would be hard to prevent major, disorienting jumps when switching.

10

Very very super cool! One potential issue is that clicking resolve “hides” the comment forever(?) and apparently without possibility of canceling or showing them again (?)

1 Like
11

Yep. One of the things that we edited out of the introductory post — and that I’ve just gone ahead and put back in there — is that we’re planning to add a way to show all of a notebook’s resolved comments (in a read-only way) in the future.

For the time being, it hides them for good.

2 Likes
12

Looks to me like a really smart solution! Especially to keep the suggestions private.
Nice work :slight_smile:

1 Like
13

Is there a way to undo a merged suggestion if it contained only comments? I just received a nice comment-only suggestion from @fil that I accidentally merged not realizing that comments get hidden when that happens. Now that I read the “Suggestion and Comments” page again, I see that it does say that comments don’t get moved, so I probably should have known not to do this… :slightly_frowning_face:

14

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

1 Like
15

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?

16

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:

2 Likes
17

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
18

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
19

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.

20

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:

4 Likes