Suggestions and Comments The friendly way to collaborate on Observable notebooks.
Have a neat idea about someone else’s notebook that would make it even better? Or are you working on a team, building visualizations and running data analyses in notebooks, together? Suggestions are a simple, considerate way to fix bugs, suggest changes, and discuss ideas for notebooks on Observable: You send comments and propose code changes to the author of the notebook. You and the author have a conversation about the changes on the live copy of the notebook itself, seeing the intended result. The author can edit and merge the final set of changes, or reject them, as they see fit. That’s it! Let’s dive in:
👋Let’s make a suggestion! Suggestions can contain comments, proposed code changes, or both. The simplest suggestion is just a comment. To comment on a notebook, click the menu next to the cell you want to comment on, then click Comment. You’ll see something like this:
html`<figure> <img style='border:1px solid #ccc;border-radius:4px;' alt="Example comment" src="https://observable-tutorial-assets.s3.amazonaws.com/suggestions/comment.png"> </figure>`
Adding a comment won’t immediately send the suggestion — a Suggest button will appear in the header, and you can click that when you’re done commenting and making all of your edits to the code. This way, you share your suggestion with the author once you’ve finished the complete thought. You can also send suggestions from any fork of a notebook, so that you can fork first, tinker, and decide to suggest the changes later on. After clicking Suggest, you have the opportunity to label your suggestion with a brief description of your changes.
👍 Discussing, accepting, and closing suggestions When the author receives your suggestion, they’ll be able to read your comments and code changes, and can choose to merge them — instantly applying them to their notebook. They can also reply to your comment threads, so you can explain, discuss, or just chat about the notebook. It’s a friendly, private space — invisible to any other readers who aren’t involved in the suggestion — and updates live, like a chat.
You’ll see the proposed change as a diff, and be able to pick all or just a few of the changes. Merging a suggestion instantly applies the code changes (and not the comments) to the notebook. Authors can choose to accept a suggestion in full, close it, or accept individual parts of it by toggling between the Base and Target versions of each cell.
🤝Getting philosophical: a humane way to collaborate
The conversation happens at your own pace.Rather than send each message immediately as you write it, you can assemble your thoughts into a cohesive suggestion and review them. To update your suggested changes after sending, click the Reshare button.
Comments and code are complementary.What better way to recommend a change to code than as live code that can be merged with a click? When reviewing changes, instantly toggle them on or off to see their effect. Comments are attached to cells so they appear adjacent to what they reference, and when a cell moves, the comment stays with it.
Suggestions are private.Trolls and attention-seekers are not welcome — and because suggestions are private, time-wasters can’t use them to push their own agenda on your notebooks. To share your brilliant commentary with the world, publish your own notebook; don’t attach to someone else’s. Authors control what appears on their own notebooks.
Comments should help you work.When collaborating or responding to criticism, it’s helpful to keep track of points you’ve addressed and points outstanding. To hide comments associated with a particular cell, click the Resolve button. (We’ll add a way to show all of a notebook’s resolved comments in a future update.)
Resolving comments keeps them out of the way once you’ve addressed them.
Have fun with suggestions! We used suggestions to edit this introductory notebook together. We hope you enjoy working with others through suggestions as much as we do, and we’re excited to hear your feedback on this new feature. Let us know what you think. 🙏
Appendix
icons = ({ vdots: `<svg viewBox="0 0 8 14" fill="currentColor" stroke="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" width="8" height="14"><circle r="1.5" cx="4" cy="2"></circle><circle r="1.5" cx="4" cy="7"></circle><circle r="1.5" cx="4" cy="12"></circle></svg>`, comment: `<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" width="16" height="16" class="w1 h1 mr1"><path d="M14 10c0 .736-.597 1.333-1.333 1.333h-8L2 14V3.333C2 2.597 2.597 2 3.333 2h9.334C13.403 2 14 2.597 14 3.333V10z"></path></svg>`, hdots: `<svg viewBox="0 0 16 16" fill="#555" style='margin:0 5px;' stroke="none" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" width="16" height="16"><circle r="2" cy="8" cx="2"></circle><circle r="2" cy="8" cx="8"></circle><circle r="2" cy="8" cx="14"></circle></svg>` })