Skip to content

Instantly share code, notes, and snippets.

@mootari
Created Feb 17, 2019
Embed
What would you like to do?
Imported notebook
{
"id": "be363ed8b6d9f3b5",
"slug": null,
"trashed": false,
"likes": 0,
"forks": 0,
"fork_of": null,
"owner": {
"id": "07362516b5994994",
"github_id": "322014",
"avatar_url": "https://avatars2.githubusercontent.com/u/322014?v=4",
"login": "mootari",
"name": "Fabian Iwand",
"bio": "",
"home_url": "https://twitter.com/mootari",
"type": "individual"
},
"creator": {
"id": "07362516b5994994",
"github_id": "322014",
"avatar_url": "https://avatars2.githubusercontent.com/u/322014?v=4",
"login": "mootari",
"name": "Fabian Iwand",
"bio": "",
"home_url": "https://twitter.com/mootari"
},
"collections": [],
"update_time": "2019-02-17T00:53:04.368Z",
"publish_time": "2019-02-17T00:53:04.368Z",
"publish_version": 18,
"version": 18,
"title": "Suggestions and Comments",
"nodes": [
{
"id": 0,
"value": "md`# Suggestions and Comments\n\n<div style='opacity:0.7;font-family:var(--sans-serif);'>The friendly way to collaborate on Observable notebooks.</div>`",
"pinned": false
},
{
"id": 1,
"value": "md`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?\n\nSuggestions are a simple, considerate way to fix bugs, suggest changes, and discuss ideas for notebooks on Observable:\n\n1. You send comments and propose code changes to the author of the notebook.\n2. You and the author have a conversation about the changes on the live copy of the notebook itself, seeing the intended result.\n3. The author can edit and [merge](https://beta.observablehq.com/@observablehq/fork-share-merge) the final set of changes, or reject them, as they see fit.\n\nThat’s it! Let’s dive in:`",
"pinned": false
},
{
"id": 2,
"value": "md`### 👋Let’s make a suggestion!\n\nSuggestions can contain comments, proposed code changes, or both. The simplest suggestion is just a comment.\n\nTo comment on a notebook, click the menu ${\n icons.vdots\n} next to the cell you want to comment on, then click ${\n icons.comment\n} Comment. You’ll see something like this:`",
"pinned": false
},
{
"id": 3,
"value": "html`<figure>\n <img style='border:1px solid #ccc;border-radius:4px;' alt=\"Example comment\" src=\"https://observable-tutorial-assets.s3.amazonaws.com/suggestions/comment.png\">\n</figure>`",
"pinned": false
},
{
"id": 4,
"value": "md`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.\n\nYou 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.\n\nAfter clicking **Suggest**, you have the opportunity to label your suggestion with a brief description of your changes.\n\n<img style='width:100%;max-width:640px;' src='https://observable-tutorial-assets.s3.amazonaws.com/suggestions/suggestion-comment.png' />`",
"pinned": false
},
{
"id": 5,
"value": "md`### 👍 Discussing, accepting, and closing suggestions\n\nWhen 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.\n\nThey 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.`",
"pinned": false
},
{
"id": 6,
"value": "md`<figure>\n <img style='border:1px solid #ccc;border-radius:4px;' src='https://user-images.githubusercontent.com/4732/52819009-1261c580-305d-11e9-92d2-b842318c230b.gif' />\n <figcaption>You’ll see the proposed change as a diff, and be able to pick all or just a few of the changes.</figcaption>\n</figure>\n\nMerging 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.`",
"pinned": false
},
{
"id": 7,
"value": "md`---\n\n### 🤝Getting philosophical: a humane way to collaborate`",
"pinned": false
},
{
"id": 8,
"value": "md`*The conversation happens at your own pace.* \nRather 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.`",
"pinned": false
},
{
"id": 9,
"value": "md`*Comments and code are complementary.* \nWhat better way to recommend a change to code than as *live* code that can be [merged with a click](/@observablehq/fork-share-merge)? 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.`",
"pinned": false
},
{
"id": 10,
"value": "md`*Suggestions are private.* \nTrolls 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.`",
"pinned": false
},
{
"id": 11,
"value": "md`*Comments should help you work.* \nWhen 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.)`",
"pinned": false
},
{
"id": 12,
"value": "md`<figure>\n <img style='border:1px solid #ccc;border-radius:4px;' src='https://observable-tutorial-assets.s3.amazonaws.com/suggestions/resolve.png' />\n <figcaption>Resolving comments keeps them out of the way once you’ve addressed them.</figcaption>\n</figure>`",
"pinned": false
},
{
"id": 13,
"value": "md`### Have fun with suggestions!\n\nWe 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.](https://talk.observablehq.com/t/let-s-talk-about-observable-suggestions/1675) 🙏`",
"pinned": false
},
{
"id": 14,
"value": "md`---\n\n## Appendix`",
"pinned": false
},
{
"id": 15,
"value": "icons = ({\n 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>`,\n 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>`,\n 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>`\n})",
"pinned": false
}
]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment