Commenting API

[hedgefield]

To complement the collaborative features in #1930, it would be a good idea to also create a commenting system. That API can then be exposed to other developers (at Yoast we'd love to use it to mark SEO feedback in the text, for instance).

Here are some mockups of what this could look like. I've aimed for feature parity with Google Docs, and tried my best to stay within the Gutenberg design spectrum, but feedback or improvements on the UI and UX are very welcome.

Here's how it could work:

• An icon in the top bar shows how many comments a document has. Clicking that will move the regular inspector sidebar aside and slide in the comments sidebar.
• The default Overview tab shows the comments in context, like Google Docs does, and the Review tab turns them into a sortable 'to-do' kind of list.
• You can filter the comments by type (so from users, from plugins, resolved etc)
• Clicking the highlight in the text also highlights the comments, and vice versa.

@atimmer has also agreed to dedicate some time in the coming weeks to help figure out the technical specifications.

Adding comments to selected text or blocks via the comment button in the toolbar

Writing a comment

Comments marked up in the text

The overview tab, listing all comments in context

The Review tab

Some takes on what the filters could look like

Mobile version of the comments overview

Mobile version of a selected comment

[karmatosed]

Firstly, thanks for starting to work on this @hedgefield. I can see it being a useful feature for users. That said I feel the approach here needs some work. I think we need to step a little back, do some research on what existing products do with commenting like this. There are some design issues would be solved by stepping away from high fidelity mockups, researching and working from sketches first. I'm not sure we've agreed a spec here either yet. Do you have any research you can share on this?

Can we also think of the flows and sketch those out? We're diving a little deep a little too quick here and need to step back and agree what is being made. I am very cautious of just designing something without getting an agreement and cohesion there.

I would after a visual mock like to get a clickable prototype of this. I have concerns with 'yet another' type of interaction happening in that sidebar and the usability of that experience. This needs to be explored.

I have strong concerns this is a little like placing a lot of Google commenting into the existing interface, I don't think it works because of that. Which is why I want to explore things and avoid following this path.

One thing needed is to think about the existing design language and icons. There is a discord between what is in Gutenberg now and these mocks that we need to unify. A good example of that is the iconography in the mockups and the interaction groups - for example the comment format.

[jasmussen]

Nice ticket.

It seems like you have some of the high level patterns right with regards to Gutenberg, though I agree with Tammie that I think it may be good to rewind a bit.

In this case, we are talking about one or several plugin APIs that Gutenberg should surface to developers. While generaly I'm a fan of "the more, the better", there are both technical considerations (is it possible) and user experience considerations (will this be good for the end user).

In the case of the button in the editor bar — I was glad to see the pattern of the sidebar toggle being reused here. A previous Gutenberg mockup had a "History" button next to Settings, which would open a revisions sidebar. However, since such a toggle button untoggles settings and replaces the sidebar with its own, it seems like it should live next to the cog, which has accessibility considerations. It also begs the question how an interface would look, if 10 WordPress plugins added toggled sidebars here. Is this an area of ux where Gutenberg should be opinionated and, for instance, disallow? Is there a different design for toggle buttons that leverages a metabox that lives in settings instead? Is there a different tab design for the existing sidebar tabs that would allow for more than the two we have?

Approaching the challenge from a different angle: is there a way a commenting feature could be implemented, which did not require a sidebar at all?

Whenever I tackle something that's really difficult, I look at the one thing the feature has to accomplish, and the tiniest unit on which it has to interact. In this case, it looks like a commenting feature, on a per-block, per-inline text basis. The obvious existing example of a system that does this, is Google Docs, which allows comments to sit on the side. Perhaps that could be the key to unlocking this?

You'd have all plugins sit in the ellipsis menu:

Perhaps you'd also show a "SEO analysis summary" in the recently merged publish dropdown: https://github.com/WordPress/gutenberg/issues/708 — sort of a last-minute "are you ready to publish" checkup.

A click on either of those, would toggle showing the yellow highlights. A click on one of those yellow highlights would show a popout menu next to the block itself:

By having the popup be invoked from the block itself, it seems like there's a way for it to be a tab accessible action. The accessibility is not fully thought through here, but it seems like it might be a more direct path to something good.

Now all of the above is speculation, to help grease the wheels of ideas. They are not fully formed ideas in themselves, and I also want to be clear that I'm not sure yet what the technical challenges of even implementing the above are, whether it's even feasible. But hopefully it can be helpful!

[hedgefield]

Thanks all, good discussion. Our in-house UX design process is different from others here I'm sure, we do skip steps sometimes because we are limited in time and manpower, but also because we do a lot of the spec during conversations and as we prototype. Those internal conversations are of course not visible here, so thanks Joen for offering some good jumping-in points to create more context.

So, to take it a step back, as I see it, these are the three options for presenting comments:

Note: I've put screenshots of the examples mentioned below in a zip file to not clutter the issue: Comment reference.zip

Inline. Example: Notion Pros: Does not require the sidebar. Cons: Interrupts the flow of the content, and can only show up between blocks, thus losing all ability to reference specific words or sentences. Takeaway: Big loss for WYSIWYG.

Overlay. Example: Pages Pros: Minimal UI clutter, does not require the sidebar. Cons: Adds another floating element to an already crowded canvas, virtually impossible to get right on mobile Takeaway: Hard to use, hard to implement.

Side(bar). Example: Google Docs, Microsoft Word, Dropbox Paper, Drafts Pros: Keeps meta information/actions about the content in the sidebar area, doesn't add UI to the writing area, is a proven concept used by millions of users. Cons: Yet another sidebar usage - is that bad though? Takeaway: Seems to offer the most bang for our buck, either placed in the inspector sidebar or as floating boxes underneath it, like Joen's mockup.

The co-opting of the sidebar highlights a higher-level thing: the sidebar is (as I see it) there to offer you a suite of tools based on the usecase you are in. For a typical workflow, we might identify:

• Writing. Sidebar closed, as little distraction as possible.
• Content editing. Sidebar open, showing block controls.
• Reviewing. That's the revision editor, but could fit in the sidebar eventually.
• Publishing. Sidebar open, showing document controls.

With this feature we add one more usecase:

• Copy editing. Sidebar open, showing the comments - or any of the above toolsets. And it doesn't have to just be comments, it could be tracking changes like Google Suggest, SEO readability feedback, references during research. Wherever we house it, it needs to be robust enough to offer these features.

It doesn't have to be two tabs, maybe one is enough, then you could also consider making it the third tab of the inspector. That would be great. And that would be a good thing to user test. Or how to display the comments. Or how to mark the text. I really like how Dropbox Paper and Drafts do it, cutting as much unnecessary metadata from the default view as possible and floating them in the canvas. But it's still some kind of UI on the side of the content, almost all the big editors come back to that pattern. So if we can agree that we want to explore that concept, I (and/or others) can make more sketches and flows examining the look and feel.

[lumberman]

Why not allow developers to create custom panels and provide access to the cursor/block events?

I don't think that creating a "niche" API will be useful for everyone. With more access to the editor state and UI from the outside, we can extend it on our own. Yoast will create content analysis tools and other developers will find 100+ more good ideas on how to integrate Gutenberg with their projects.

[atimmer]

To be able to build this, comments would have to be persisted to the server. And these comments need a reference to a block. While thinking up a way of making this possible I realized there is no way to identify a block. On the client side, each block has a UUID, but these are changed each time someone opens the editor.

While discussing this needs with @aduth, @youknowriad and @gziolo, we uncovered two more use-cases where identifying blocks is useful. The first use-case is collaborative editing. The second use-case is for block versioning and migration. The discussion starts here: https://wordpress.slack.com/archives/C02QB2JS7/p1511183681000329.

Block index doesn't work because the block could be moved and the comment needs to move with it.

Technically, we've identified a few solutions:

• Persist the UUIDs to the block comments in the content.
• Persist blocks elsewhere and make HTML content a view of the data.
• Persist the meta with an identifier and reference that from the block.

I think the first option is the most pragmatic, but it muddies the block syntax. The second option is different from the goals outlined in the editor technical overview. The third option is the easiest to implement, but it doesn't solve the problem of being able to identify a block. Given that a block is the first class citizen in the domain, there should be a way to identify it.

[karmatosed]

First, thanks for all the design research @hedgefield. It's is important we follow an open process with this and work through things.

It's interesting when you say a 'sidebar' for Google Docs. It also got my thinking, in your mocks it's a 'literal' sidebar. Yet, Google docs isn't. I think one big issue comes when you are literally using the sidebar and all the chrome in it. Something to work with in sketches.

Out of all I think Draft, Paper and Google Docs are worth using as fuel for inspiration. I feel Pages and Word are a little limiting and dated in their implementation. Notion is interesting, but I can't help think a huge document with a lot of comments would get intense to navigate using that format. Maybe something worth testing.

I'm interested in sketches around this - not full mocks right yet, I think it's worth considering a more open UI. I'd love to see what others think along with this too.

Here are some initial ideas of my own, just super rough sketches.

First, you have the comment indicator. This is 'enabled' when there are comments and disabled when none. Maybe we have a setting somewhere to not allow comments - potentially on network/config file.

Next, the commenting itself. When you highlight a section it simple pops up an indicator that you can comment.

Once you comment, it would show and you could interact there and then - not the sidebar isn't being activated for this.

A few points about the commenting:

• Where possible showing a 'face' and fact someone is human leads to better comments, if we know that from avatars, let's show it. If not, just the name or some indicator.
• Let's have some simple emojireactions. I would like us to not include the thumbsdown as that can be done with a closure. Let's have potentially: 'thumbs up, star, smiley face and heart' - we can discuss this.
• Having a simple way to close and accept is key.
• Reply's open but are disabled until you click in. This encourages conversation.

This sketch is on purpose distilled right back. Let's get the basic notion of a commenting language down then think of the advanced options that other plugins need to hook into. We have a strong pattern now of hooking as @jasmussen said into the ellipsis, this could solve the advanced cases.

[hedgefield]

Good stuff. I like the idea of having the comments floating in the canvas, not stuffed into the sidebar chrome. I sketched out a flow for this.

1. Selecting text to comment. Having the indicator appear next to it is fast, but I wonder if it doesn't break consistency. For this sketch I added the comment button to the docked toolbar.

2. I like showing just as much UI as is needed, so just your gravatar and a single-line text field to start with. That way you can still click anywhere else to dismiss the comment prompt.

3. As soon as you type, the save/submit/post and cancel buttons appear.

4. Once posted, the post date appears along with the approve/reject button and the reply field. I realize that adding the submit/cancel buttons for the reply here too would make the comment a bit long, but I also don't know if approve/reject icons are enough, they don't seem very accessible. We could consider making the reply submit/cancel buttons smaller, or something of that nature. The layout of the comment box could use some attention.

5. And then there's the comments indicator. It might be nice to compress the comments into a counter next to each block, or adding it to the top bar, although that might be too close to the add comment button.

[jwold]

So happy to see the progress on this idea! Wanted to cross post an idea (in a very similar vein) that was added to Trac: https://core.trac.wordpress.org/ticket/39192.

[jaswrks]

@jwold @hedgefield and others. I'm proposing an object model for annotations in https://github.com/WordPress/gutenberg/pull/3807 if you'd like to offer feedback there it would be well received by me. Thanks!

[karmatosed]

@hedgefield sorry about a little delay in getting back to you, let me dive right in now! Thanks for taking the sketches and iterating. Also props for stepping into sketches yourself, we can iterate fast this way!

Having the indicator appear next to it is fast, but I wonder if it doesn't break consistency. For this sketch I added the comment button to the docked toolbar.

I still think contextually it makes a lot of sense. I am interested why you think it breaks consistency?

I like showing just as much UI as is needed, so just your gravatar and a single-line text field to start with. That way you can still click anywhere else to dismiss the comment prompt.

How will people know they can perform actions on the comment? Is typing enough? How will they type if it's an existing comment?

We could consider making the reply submit/cancel buttons smaller, or something of that nature. The layout of the comment box could use some attention.

Maybe let's considering icons here like my mock? I do feel with 'approve and reject' that's a lot of visual going on. Could we scale back by using iconography? Will it still have meaning?

@jwold great to see you have been thinking similar. What would you suggest to bring from that into this work? You are most welcome to join in the sketches here, to bring your insights.

[hedgefield]

No problem! I know you've been busy :)

I am interested why you think [a floating comment indicator] breaks consistency?

Well, almost all the actions you can perform on a block are in the toolbar (with the exception of delete and move). I wondered if it was smart to add another piece of chrome around a block. But there is definitely something to be said for having it appear right next to where you want it, too. So maybe we start with that and test how it feels.

How will people know they can perform actions on the comment? Is typing enough? How will they type if it's an existing comment?

A text input field that says Type a comment/reply here... seems like a well-established pattern to at least get people typing, and if they see the comment/cancel buttons appear once they do, I'm sure they'll understand how it works. Though good food for a test.

The Reply input field is always shown under the existing comment. That leads nicely into your next point:

I feel with 'approve and reject' that's a lot of visual going on. Could we scale back by using iconography? Will it still have meaning?

I do feel you on all the buttons becoming a bit much, but whether icons alone are better I feel like @afercia is better equipped to say. I chose buttons because plugins might want to adjust the text of the button based on what they use annotations for (for instance, suggesting a link, then the buttons would say Add link and Ignore).

I made a few more sketches, two different looks for how adding a reply to an existing comment could look. This time the annotation is for the whole block, since that's the first version @atimmer will be building.

[afercia]

It would be great to start thinking at a workflow to make comments usable with the keyboard. I guess some focus management would be required.

Aside: please don't use placeholders as replacement for labels, see Type your comment here...

[karmatosed]

@hedgefield:

So maybe we start with that and test how it feels.

Yes I think it's important to explore.

I think for now lets go with icons.

[hedgefield]

I've done some more exploration on this and made new mockups working off of the latest sketches. I think these fit the vibe of Gutenberg much better already.

Adding comments

For the first implementation, adding the option to the ellipsis menu seems like a good fit. I'd rather have it in the toolbar but this would do too.

Writing a comment

Kept the UI minimal and similar to other popups in Gutenberg. The empty space where the date goes was a nice space to add a label to the input field, and the textual buttons keep the actions accessible without adding the visual weight of a button shape.

Posted comment

Starting with just the block level, I imagine we would allow multiple comments on one block (not counting replies).

A reply

Expands right below the reply button. In the case of multiple first-order comments, replies might need a little horizontal offset.

Defocused comments

When expanding the sidebar again, comments might shrink down to just display a clickable indicator. I like using the gravatars instead of an icon or a number, but other ways can be explored.

[karmatosed]

@hedgefield firstly thanks for doing this. It's good to see the evolution. There are a few things we seem to have dropped using that I was keen on and some design elements I think we can iterate on. Let's do that over diving into making this right now.

To think about:

• The double avatars is incredibly confusing for users. Let's go back to having an indication to number of comments. Imagine non-facial avatars and the confusion that could cause.
• I strongly think icons work and would like to see that explored.
• I don't think we need to go with drop shadows, let's not add a depth that the interface doesn't have.
• 3 UI actions on one level isn't great, lets really consider the interactions from my sketches: https://github.com/WordPress/gutenberg/issues/3026#issuecomment-347008540
• Having a side arrow then a bottom one with 2 comments out is super confusing from a visual interaction level. Let's avoid that and go back to the layering seen in my mocks.
• I am not convinced adding the ellipsis is a good way forward. Can we explore having this in the top bar please?

Let me know if you are happy working on this or want me to dive into a mockup.

[afercia]

Some accessibility considerations on the sketches and mocks seen so far:

Keyboard interaction: once the sidebar appears, it's not clear how a keyboard user can move from a block to the sidebar and back from the sidebar to the original block

Linearised content: for many users, navigating content is a linearised experience; I'd like to see sketches and mocks taking into considerations content organisation and information architecture before any visual aspect. Specifically, when inside the sidebar, as an user that navigates content in a linearised way, I need to know what the comment is before getting to the available actions. A good order would be:

• comment author and meta
• comment content
• actions Instead, having the actions before the content would force me to first go to the content to make a decision on the subsequent action, then navigate backwards to the actions. Far from ideal.

Icons: they don't have an universal meaning and they would need tooltips in any case. Additionally, the "checkmark" and "X" icons I see in the sketches have different meanings in some cultures. Considering they should be placed after the comment content (see previous point) I'd strongly recommend to not use icons and use plain text for the actions controls. Plain text can be translated in a meaningful way in any language and for any culture.

Controls without context: once there will be many comments and replies, the sidebar will have lots of controls labeled "Reply", "Delete", etc. Regardless of the number of actions or if they will be icons or text, they will have be labeled in some way. Having several controls with the same text is, more or less, like filling up a page with lots of "click here" links: no clue what they do when read out of context. In core, this issue is often addressed adding some meaningful, visually hidden, text. For example: Edit “Hello world!” Move “Hello world!” to the trash View “Hello world!” etc. In the same way, the comments controls need context. Comments don't have a title though, so wondering what the best option would be. Probably some text that is a combination of the comment author name, comment date, etc.

Emojis: hard if not almost impossible to make them accessible. For reference, there's a core ticket about this: https://core.trac.wordpress.org/ticket/37486. Not to mention an "emoji inserter" should be accessible too. So my question is: are emojis really necessary? Do they add any great value to this feature?

[karmatosed]

@hedgefield and myself talked a bit about kicking off this again, at least to the point of getting a design, even if it doesn't get into v1. Here are some sketches that are a next level from my doodle but not much more, I am keen Tim you get to follow on with the design, with some adjustments.

@iamthomasbishop I am cc'ing you in here as none of these designs are worked from a 'what would work on mobile'. I am not suggesting we strip it all out, but what you have there insight wise could really help us evolve. It's crucial I feel that commenting still works on mobile.

[jasmussen]

@karmatosed Everything about those mockups look good, except for the position of the comment icon. We should see if we can fit it to the right, next to the Cog, like every other extension. In fact, there's a ticket to move the document outline over there as well, with a number of further reasons for why the right side is a better place for that: https://github.com/WordPress/gutenberg/issues/4287

The good news is the API for showing icons on the right is virtually done, so this would be easy to hook into.

[karmatosed]

@jasmussen that sounds like a solid plan to move the comment icon. @hedgefield when you iterate can you take that into consideration?

[hedgefield]

Will do. Looks good! I hope to get an iteration in this week.

[karmatosed]

A little update on how this could work a little more refined. @iamthomasbishop and myself had a little chat about mobile and it resulted in some interesting thinking. We need to consider this action similar to linking as you would highlight to add a comment. With that in mind, what about adding the 'add comment' in the toolbar the block? The benefit of this is easier working across all devices. For example:

Further more, the link and commenting icons become passive when no selection of text happens. You also can see in this screen how comments show to the side, text remains highlighted (let's work on the color to get a really accessible one):

Notice, the top indicator now is active, showing comments? That indicator also now doubles up as a stream. If you click it you get this:

This log is very similar to the Google docs one. The benefit of this is that on smaller devices maybe you only show this log.

What do people think?

[iamthomasbishop]

This is awesome @karmatosed - you beat me to mocking it up! Sorry in advance for the brain dump :)

For the doc-level Comments UI, I'm wondering if it should be in the sidebar/inspector form, so that it doesn't cover the content? On mobile, avoiding covering the content will be virtually impossible, but I think a sidebar/inspector would be more appropriate and could feel more natural (and be easier to implement?) on smaller screens.

The trickiest thing with this on small screens imo is going to be the detail-level interactions w/ inline comments. Because we don't have room to show the comments off to the side of the content like we can on desktop, I imagine it makes most sense to do one of the following when the user taps on an inline comment:

1. Open the doc-level Comments UI (think a Table of Contents for all of the doc's comments) and send the user to that specific comment (some anchor point) inside the UI. Probably the easiest option, but a busier UI that might cause confusion because the comment in question could be mixed with other comments:

2. Open the doc-level Comments UI but hide all other comments programmatically - meaning the doc-level UI is only accessible from the icon in the top toolbar

Similar to option # 2 but a distinctly separate UI from the doc-level Comments UI, we could open a separate inspector/sidebar that only shows the comment in question. Maybe not the best option technically.

As an alternative idea for the separated doc-level Comments UI, we could also put the Comments UI on the top-level sidebar, alongside the Document, Block tabs. It seems like we would prefer to keep Comments detached, but it would look something like this:

[hedgefield]

Great additions @iamthomasbishop, exactly my two first thoughts.

To the popover/sidebar matter: A sidebar seems like a more stable way to display a stream/feed yeah. That would use the same pattern as other extensions, especially also with the icon being shown in the top bar, so that's nice.

As an ancillary point to that, I found it challenging that there would be two comment icons in view that do different things (especially if people have the toolbar fixed to the top), so I thought maybe we could take the stream idea a little further towards a place for document notifications? Things like edits by others, changes to metadata etc. At least an excuse to use a different icon ;) That might be something to detach from this idea for v1 too, and explore in a separate ticket.

To the mobile screen estate matter: I was thinking something along the same lines. @karmatosed mentioned we could resort to only show the comments stream on mobile, and I tend to agree. In Google Docs you can reply and resolve from there too. Those also include the highlighted text, so you have the context right there. The only difficulty is when you want to edit the highlighted text. I could see that you tap on a comment and the sidebar closes to bring you to your content, but after you make the edit, you'll want to resolve the comment. How to get back to it from there, I cannot yet see a really intuitive way, other than re-opening the comment sidebar again to find the one you need.

Anyway, I did an iteration on the commenting UI itself, let me know what you think. I tried to keep this one as minimal as possible. My only gripe is that I couldn't yet find a nice place to put a label for the reply field without making things too busy, but I'd like to add that to ensure the a11y is covered.

Selecting to comment. Icon appears in the toolbar.

UI to leave a comment.

I reused the Apply button from the link popup to have a button there for a11y but still keep everything within the input field visually 👌 The yellow is AAA compliant too.

The posted comment with actions and reply field. The actions don't yet feel... super.

A thread

For adding multiple comments in close proximity I trust that we can make it work like Google Docs does its sorting and placement. It seems a bit magical so I'm not sure exactly how to spec for that.

[chrisvanpatten]

That looks amazing!

One question: most of the mockups above make it pretty clear how you would comment on a chunk of text, with highlighting. What might be done for commenting on non-text-based blocks?

Google Docs sort of allows you to comment on non-text things, by sort of applying the highlight around the content:

Obviously Google's implementation is kind of hacky, but I think there's something to it. Maybe a border on the block matching the highlight color could be an option?

(Also I think it's implied in the mocks above, but to confirm: are comments only visible when you've actively clicked into that highlight? This is really only an issue if comments aren't always visible. Otherwise you'd be able to see the comment next to the block, so another visual indicator probably wouldn't be necessary.)

Also if the answer is "commenting on non-text content would be too big a challenge and delay getting anything in at all" then it's probably fair to skip for now. Thought I'd ask though :)

[hedgefield]

Good question, and I could definitely see that work. Colored borders were something I explored with comments on entire blocks - I see that wasn't in this issue though. But it makes sense, yeah.

[jaswrks]

On the technical side, assuming this Annotation API ends up being used, there's no problem selecting non-textual elements. Any type of DOM node can be selected individually or as part of a selection range.

I played with this a bit in a fiddle: https://jsfiddle.net/jaswrks/1cLaeyfd/

[karmatosed]

As it's all just content wouldn't we just have it the same color @hedgefield as in my mocks? I don't think we need to do borders around things, that could confuse. Let's maybe explore with a top/bottom padding space over adding to edges. This will come out in prototyping.

[hedgefield]

It's true of course that the border around a block is not visible when no block is focused... How do you see that top/bottom padding space?

[karmatosed]

I think maybe lets in this case get the design worked up for the other cases and iterate adding that in, it all depends on that direction @hedgefield and something that may come up whilst you are working on it.

[hedgefield]

I did a few more mockups for highlighting media.

My initial take was to apply the same flow, but you cannot drag to select media like you can with text. Well, you can, but it selects the whole block and you can't edit. Clicking the media, instead, brings up the controls for that particular image/video/what have you.

So I figure at that point the commenting flow I mocked up above would apply. Then it just comes down to how the highlighting looks. I've tried three things and I think I like 2 the best.

I toned down the yellow I used in my previous mockup, because while it works for small bits of text it's way too intense for borders and overlays.

[karmatosed]

Thanks for that @hedgefield, my feelings are the 3rd option avoids issues with padding and spacing for other elements, for example the placeholder states. Let's maybe go with that moving forward as I see other apps do the same, just highlight layer.

[hedgefield]

Alright cool, that would definitely have been my next choice, both 2 and 3 have elements of what traditional highlighting does. Maybe 3 is more obvious at a glance, yeah.

@jaswrks were you still working on the technical side of this? Do you need anything more to implement the latest iteration we've discussed here?

[jaswrks]

I'm not working on this at the moment, but I love the work everyone has been doing and I've reviewed the latest design ideas. Here are some things that might need further clarification on the dev side.

I think some of these questions are just from looking over different ideas in the mockups above, and now I'm trying to determine exactly what we decided on.

• Will we lay the stream of block-specific comments on top of the Gutenberg sidebar if it's open? Or, will the display of block-specific comments force the sidebar closed if it's open? I wonder, if the sidebar is closed, how this might impede a user's ability to make edits based on feedback they received in the comments.

• On a desktop, what are all of the different states that a stream of block-specific comments can have? Showing those states in a mockup and further clarifying the actions that cause a transition from one state to the next might be helpful.

• Is there any state in which the stream of block-specific comments are automatically filtered to only show comments that pertain to a specific selection within the block?

• Any thoughts on how annotated selections can best coexist with editing functionality? For example, how would a user intentionally add a highlight to some text in their editor if it's already been highlighted because it's been annotated?

[hedgefield]

Good questions. I'll do my best to answer them, but feel free to chime in if you have opinions on this, and I'd love to hear @atimmer's take too.

1. I think in our mind we did consider the sidebar and the comments to be mutually exclusive. To show them next to the blocks we need the space. Basic editing can be done without the sidebar, and I think if you have to open it to adjust something, that's not a huge hassle.

2. I think we captured all the states in the last round of mockups:

   • commenting (a comment box appearing for you to type in) happens via selecting some content and pressing the comment icon in the toolbar. The reverse can be done by clicking anywhere outside the comment box to deselect the text and dismiss the comment box (and what was in it).
   • commenting > commented via pressing Enter or pressing the comment button.
   • replying is similar to commenting and is triggered by focusing the reply input field.
   • accepted triggered via pressing the accept button on the first comment. Removes the comment stream and the highlight.
   • rejected is the same as accepted, but triggered via the reject button on the first comment.

3. For v1 I'm not sure we'll be filtering the comments. I mean if there are loads of comments in a specific area, they should be smartly arranged like Google Docs does to make sure that the one you have the cursor over is the prominent one.

4. Highlighting is a tricky one. Is it done with an opaque background color or a transparent overlay color? Either way, if we make sure the annotation color does not appear exactly in the highlighting palette you should be able to recognize it, but this might be something we need to test.

[karmatosed]

Thanks for the awesome questions @jaswrks and answers @hedgefield. If I may add some thoughts:

Will we lay the stream of block-specific comments on top of the Gutenberg sidebar if it's open? Or, will the display of block-specific comments force the sidebar closed if it's open? I wonder, if the sidebar is closed, how this might impede a user's ability to make edits based on feedback they received in the comments.

Maybe by being open it closed the sidebar? Is there a case to have both open?

On a desktop, what are all of the different states that a stream of block-specific comments can have? Showing those states in a mockup and further clarifying the actions that cause a transition from one state to the next might be helpful.

I think @hedgefield it could be good to have a clear set of final mocks of those states maybe?

Is there any state in which the stream of block-specific comments are automatically filtered to only show comments that pertain to a specific selection within the block?

I agree with @hedgefield that lets leave this for v1 and consider it later.

Any thoughts on how annotated selections can best coexist with editing functionality? For example, how would a user intentionally add a highlight to some text in their editor if it's already been highlighted because it's been annotated?

I agree here too that testing is needed, going to be a finer detail we need to work through.

[jaswrks]

@hedgefield @karmatosed Thanks for the follow-ups :-)

---

@karmatosed writes..

Maybe by being open it closed the sidebar? Is there a case to have both open?

Imagine someone reviews one of your blocks and writes the following annotation:

Please make the following changes:
- Enable drop caps on this paragraph.
- Highlight the word "Hello" with background color #0E9947
- Set the text color on the word "Hello" to #F3FFF8

Or, imagine Yoast SEO tips providing a list of suggestions.

So now, if annotations contain TODO lists, I just wonder if folks will want to reference the list (in the annotation) while the sidebar is also open; i.e., so they can cover all points raised in the comment, copy color codes, or read through something else.

Since the sidebar is also a part of the editor (containing editing tools), then forcing it hidden or making the two mutually exclusive seems like it might be problematic. It would be nice if there was a way to reference comments while still being able to access tools in the sidebar. I'm not quite sure how we get there though.

[hedgefield]

If I may think freely for a moment, your word choice of "referencing comments" got me thinking about the way iOS creates a contextual back link when one app sends you to another. In the same vein, I had some ideas on how to handle comments vs sidebar:

• Some kind of edit button in a comment that opens the block settings, and adds a return to comment link to it somewhere so you can quickly switch between the two.

• Collapsing comments to an icon when the sidebar is open, which can reveal the comment in a popover on tap.

• On desktop, maybe the sidebar and comments don't have to be mutually exclusive. Maybe toggling the comments on moves the text to the left and uses the combine whitespace to show the comments between the content and the sidebar. When there is not enough space for that, it shows only the comments, and turning the comments off turns the sidebar back on (if it was on).

Thoughts?

For the final flow of adding comments I'll make another interactive mockup so everything is clear, good call @karmatosed and thanks for chiming in on the other ideas.

[hedgefield]

Here is an interactive prototype of the basic commenting flow (select text, add comment, reply, resolve):

https://sketch.cloud/s/8kDE7/all/page-1/4-resolved/play

It was good to do this because I had a few more thoughts while working on it:

• Flow-technically, Accept and Reject end up at the same place. It's just an indication of whether it was resolved positively or negatively. So I considered: could we make due with simply a Resolve button? If you don't want to accept something you can say so in a comment first before resolving. Cleans things up a bit more too.
• I considered adding an Edit and Delete option to the individual comments, but I'm not sure that's super MVP? I was even surprised that Gdocs and DPaper do include it, it feels a bit like tampering with the historical record, so to speak.
• Is it necessary to be able to hide comments when they exist? As seen in the mockup, they can exist next to the sidebar, and if there is not enough screen estate, opening the sidebar could hide the comments.
• I almost feel like some kind of comment log may be needed for MVP, it feels a bit ethereal this way, having no evidence left over after resolving (except for presumably the email notification that was sent). But maybe that's okay?

The Sketch file for this prototype can be downloaded so if anyone wants to tinker with it themselves that's possible.

[karmatosed]

I considered adding an Edit and Delete option to the individual comments, but I'm not sure that's super MVP? I was even surprised that Gdocs and DPaper do include it, it feels a bit like tampering with the historical record, so to speak.

I think for usability reasons having edit is good to have in MVP, imagine if you make a spelling mistake.

[karmatosed]

I have to say I am not super keen on resolve @hedgefield. I don't think it says what people want and adds an extra step. Could you iterate not having that?

[jaswrks]

@hedgefield writes...

As seen in the mockup, they can exist next to the sidebar, and if there is not enough screen estate, opening the sidebar could hide the comments.

That seems doable to me. So we'd detect the available whitespace in the editor and if there's enough, show comments together with the sidebar. If not, force the sidebar hidden to make room for comments. I'm assuming in that scenario (not enough space) we'd want the sidebar and comments to become mutually exclusive; i.e., opening one automatically hides the other.

I almost feel like some kind of comment log may be needed for MVP, it feels a bit ethereal this way, having no evidence left over after resolving (except for presumably the email notification that was sent).

I agree. A toggle somewhere that shows a history would be nice (archived or otherwise).

[chrisvanpatten]

I agree with @karmatosed. I like the idea of a resolution/approval workflow, but I also think it introduces a lot of additional UX questions. (Does it generate an alert? Who should get the alert? Does resolving delete the comment history? Etc.)

A good chunk of the publications we've worked with actually don't use Google Docs' resolve feature at all, they'll just delete the comment or ignore it once the issue is solved.

[hedgefield]

Ah interesting, just leave out any official sort of resolution workflow? That would make it a lot simpler to build yeah. Would you say add a delete option to each comment? I could then see that deleting the 'source' comment deletes the whole thread, and deleting individual replies just deletes those from the thread.

[jaswrks]

What about "open" and "closed"? Or "open" and "archived"? i.e., more like an issue tracker.

[karmatosed]

This issue is buzzing! So much good input from everyone.

@hedgefield with regards to resolution I think having approve is ok it's the two step of 'resolve' that is an issue. As a concept one flow to mean 'reject/approve' like that just doesn't really fit. I'd suggest looking at what Google docs uses here.

Would you say add a delete option to each comment?

I would have what I originally suggested here (doesn't have to be icons):

@jaswrks whilst those terms totally work for issue tracking I am not sure in terms of a writing application - which this is - they do.

[chrisvanpatten]

I'd suggest looking at what Google docs uses here.

Google Docs uses a single "resolve" option for normal comments:

And an accept/reject flow for when you're in Docs' "Suggestion Mode":

[karmatosed]

And an accept/reject flow for when you're in Docs' "Suggestion Mode":

@chrisvanpatten thanks for the screenshots. My thinking in suggesting this is that we don't have right now modes, the accept/reject by default makes sense. Of course if it's your own comment you'd not see these.

[chrisvanpatten]

@karmatosed I'm a bit concerned that an Accept/Reject flow makes the most sense as part of an explicit suggestion/approval mode (as it works in GDocs), which Gutenberg doesn't have at the moment. In Google Docs, accepting automatically updates the content to use the suggested change; rejecting removes the suggestion and leaves the content. While Gutenberg could have that (and long term would be very cool!), it does add a whole new dimension to the issue.

We've also built editorial comments tools for clients (with MCE views in the Classic Editor that get stripped out on the front-end), and while I don't have any hard stats I'd guesstimate about 2/3rds of the comments I've seen clients make on content wouldn't really fit an accept/reject duality.

Ultimately though I think the value of getting comments into Gutenberg is far outweighed by my concerns… so ultimately I'll be happy with whatever direction we go :)

(I do also think it could be worth considering getting a comment flow in place without any type of resolve/accept/reject functionality, and use that as a springboard for additional user testing, research, etc. on resolution flows, which I'd be happy to sponsor.)

[jaswrks]

@karmatosed writes...

Whilst those terms totally work for issue tracking I am not sure in terms of a writing application - which this is - they do.

Good point. I'm not sure they do either. I do like @chrisvanpatten's idea of using either nothing at all for right now, or something really generic, and then using that as a springboard for additional user testing. Maybe later we can determine what all of the most popular use cases end up being.

As a more generic set of actions, I like:

• Open: self-explanatory and works for a variety of use cases.
• Archive: Indicates closure, but with the expectation that you'll still have access to it. And it seems to fit with the idea @hedgefield was playing with earlier with respect to a log...

  I almost feel like some kind of comment log may be needed for MVP, it feels a bit ethereal this way, having no evidence left over after resolving (except for presumably the email notification that was sent). But maybe that's okay?

[karmatosed]

@chrisvanpatten, my thinking on having accept and reject goes a little beyond just commenting and into how plugins likely will use commenting. I feel in version one having this is a good step as a result.

(I do also think it could be worth considering getting a comment flow in place without any type of resolve/accept/reject functionality, and use that as a springboard for additional user testing, research, etc. on resolution flows, which I'd be happy to sponsor.)

Sponsoring some testing would be amazing, thanks for the offer. What were you thinking of?

It's worth saying I absolutely see what we are adding here as version one, but we need to consider the uses of that version one.

@jaswrks as shown in this original mock I made, I am very keen on the log being in version one :)