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: #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 #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:
  Commenting API #3026 (comment)
• 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: #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.

[hedgefield]

Like the Inserter you mean? Yeah I definitely think matching the size with the content is best if it remains a popover. I made it a little taller in the prototype so it would cover what happens below it in case the prototype flow went wrong somewhere.

Are there any other things to add or edit in the log? Then I'll work on a quick dedicated mockup for that.

[karmatosed]

Like the Inserter you mean?

Yes the block library - that's a better name as it is a container of blocks in this case to browse.

I think right now working on a mock would be great, I am really happy with the direction this is going and thanks for taking this on the journey it's been on ⭐️

[hedgefield]

Here we go. I tried three different designs - one that fits the popover style, one that goes a little bit towards the sidebar to give some more contrast, and one just actually in the sidebar. I'm thinking about if we'd want actions in the log as well, I feel like maybe just clicking on comments that are still open just closes the log and focuses the comment in the editor?

[karmatosed]

@hedgefield I really like the one that looks more like the popover. My only wonder is are we using a distinct UI to have 2 different functions but I think it looks 'similar enough but different enough' to be ok. We may want to test into prototype that and the sidebar - I don't love the sidebar but it's got merit to try.

[hedgefield]

The sidebar does feel a bit constricting compared to the popover, but I agree the merit could be found in the fact that it uses an existing pattern and avoids another UI overlap. On mobile there would probably not even be a visual difference between the two forms so we can test what works best for desktop use.

I've updated the mockup with the popover design and did a rudimentary pass on clicking unresolved comments in the log to focus them in the document. The flow might not be watertight everywhere by virtue of Sketch prototyping being fickle, but I'll work more on that tomorrow and do a version with the sidebar log as well.

https://sketch.cloud/s/ElGQq/all/page-1/start/play

[karmatosed]

@hedgefield thanks for all your work with this. I really like the popover, right now my feeling is lets go with that option more like the block library. We can always get data back to iterate based on. Happy to see sidebar though.

I do think it's a good path forward now to get into prototype. Let's also consider developing this in a plugin maybe? My thinking is it can then allow us to easier usability test and not be tied to v1 closing off for features. What do you think?

[scallemang]

Hope I'm not derailing the conversation and that this is a pretty quick question for y'all: Whereas the discussion has been around collaboration among content creators, do you envision this feature could have a front-end application for user commenting on a site in the style of Genius or Medium 1.0? Just asking as someone interested in textual commentaries. Thanks so much!

[hedgefield]

Hi Samuel, thanks for letting us know you'd be interested in such a feature! I had not personally considered it yet, but it sounds like an interesting usecase, and certainly something we can explore in a next iteration.

@karmatosed Yeah I wasn't expecting this to get in before feature lock anyway, but a plugin is a good idea to be able to quickly iterate and test things. I'll discuss if we can get that going from here, since @atimmer was also working on annotations/markings.

[karmatosed]

@scallemang I think front end this possibly could be a useful plugin at least in first instance. That's a great thing for someone to explore once we have the infrastructure down in version one.

[scallemang]

@hedgefield @karmatosed Thanks, y'all. Looking forward to watching progress. Not the world's best or even medium-est programmer, but hopefully I can help out at some point after a v1. :)

[karmatosed]

@scallemang thanks for your contributions, even a comment is an awesome contribution! If you have time to test and even help where you can it all adds up.

[mtias]

The API architecture for supporting this has been merged. Leaving the issue open for a future use of it to power comments.

[uxkai]

@jaapwiering and I are worked together today at Yoast’s WordPress Contributor Day to take a look at this issue and - if possible - provide feedback.

We would very much appreciate the possibility of Annotations in WordPress and it’s great to see all the effort that has been made so far on this topic. This feature could be very valuable for collaboration on content and would create a workflow similar to Google Drive, Dropbox Paper, Notion.so and the like.

We believe that the following points are essential for success:

1. Annotate on text level
2. “Add annotation” button as close as possible to the selected text
3. How to present an annotation in relation to the content
4. Don’t show singular annotations in the sidebar
5. Annotation history in sidebar

1. Annotate on text level
We think annotations in WordPress would be a feature that will be mostly used by content creators (e.g. corrections of typos, alternative words and sentences). Therefore, the level on which it links to the content of a document should be the Text level (the smallest selection should be one individual letter).

An annotation feature that targets on Block level (a paragraph) or Document level will have a limited usability, because the content creator cannot select on the right level (text). We cannot imagine a use case where annotations on Block level or Document level would be useful.

2. “Add annotation” button as close as possible to the selected text
We love to make so-called comments (= annotations) in Notion.so. Why? The button to add a comment is presented very close to the text selection where you want to insert the comment, even before the “bold” and “italic” icons (see picture below). So it is logical step to create a comment (even if it’s only for yourself, instead of just marking the text).

A Paragraph comment (WP: Block) is inserted by clicking the selector at the start of that block and insert a comment.
A Document comment is inserted a if it is ordinary content, only in a different panel.
All very straightforward and logical.

3. How to present an annotation in relation to the content
Annotations should have a visual connection to the point where they are inserted in the content.

In Notion.so, comments are initially presented on the right next to the text, as a text balloon with the number of comments.

Clicking this balloon opens a panel giving you options for adding, resolving or deleting the comment. Resolved comments are found in a different tab in the same panel.

We believe this is beautiful, non-intrusive and functional (in the opposite order).

The comments in Google Drive are already opened and more “in your face”.

We like the small icons which can be used to open/display the annotations (like in Notion), but that’s a matter of taste.

4. Don’t show singular annotation in the sidebar

The functional aspects of the sidebar in the Admin Panel are not clearly defined yet and it often seems to be a place where you can drop any functionality. In our opinion the sidebar should be dedicated to functionality on the Document level (and not the Block level).

The left side of the top toolbar contains functionality on Block level. The right side contains functionality on Document level. Currently there is no clear visual separation and the clearness of the interface would improve by adding a line and visual alignment with the sidebar.

Since the Annotations should be used on Text level, we think the sidebar is not the correct place to present them. A floating panel would be better, though we are not sure of the accessibility of that.

5. Annotation history in sidebar

We think that a pulldown menu with an icon that contains the Annotation history is not the best solution. The pulldown is not very accessible and it clutters the top toolbar. The Annotation history could be presented in a new tab in the sidebar, because in our opinion this is part of the Document level.

[LarsKemmann]

What is the status of this? I've been working with a content team that is trying to go all-in on WordPress (today they're authoring and editing in Google Docs, and then manually moving content to WordPress for publishing), and this is really the only feature that's holding them back. I'd love to be able to give them an idea of what to expect.

[Soean]

@LarsKemmann Currently there is no active development on this topic. This is part of phase 3 of Gutenberg Collaboration — A more intuitive way to co-author content. At the moment we working on phase 2 Customization — Full Site editing, Block Patterns, Block Directory, Block based themes. So maybe in 2021 this issue will become more relevant again.

More information: https://wordpress.org/about/roadmap/ and #17949

[LarsKemmann]

Thanks for the info @Soean - I really appreciate it and will check back in 2021! :)