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

[hedgefield]

Okay, so shall we say this?:

• We do the log, just as a chronological list of all comments, with no actions or anything, purely historical.
• We do archive as main action, and edit and delete as secondary actions, hidden behind a popover like Google Docs does. archive is for comments that you either accept or reject but should still be remembered. delete for just if you do a dumb comment that you regret (and edit if you can still save it).
• Archiving comments will remove them from in the content area, but they still live in the log.

[karmatosed]

@hedgefield I still standby hiding edit/delete isn't the best. Can you explain more why they are secondary and not primary in the context of comments on content? I want to make sure we're on the same page and not totally sure we are. I ask this as I think they are primary for our use case which is why I don't agree the model in Google docs translates. How also do you see delete different from archive or approve?

I also think having archive as a main action is confusing, archive says you close not that you then interact. I still think this as a solid approach to going forward:

[hedgefield]

Well, if you make a comment, you'd only want to edit it if you made a mistake and only delete it if you realize it's not useful or wrong (I'd reckon), which hopefully would be relative edge cases compared to resolving the comment itself.

That said, delete could also be reject (minus the fact that it won't be removed from the log). I can see how people would enjoy having the yes-no choice on a comment even if they're technically no different in what they do. So approve/reject could be top-level choices and I can move the edit somewhere else.

I'm just not that keen on icon buttons without labels, and I fear otherwise it might get a bit crowded. We did try three top-level actions before which was not great.

[karmatosed]

Well, if you make a comment, you'd only want to edit it if you made a mistake and only delete it if you realize it's not useful or wrong (I'd reckon), which hopefully would be relative edge cases compared to resolving the comment itself.

Totally, that's why showing different things per person makes sense not having fixed settings. For example you would only approve another's comment.

I'm just not that keen on icon buttons without labels, and I fear otherwise it might get a bit crowded. We did try three top-level actions before which was not great.

It's about balance and I think a tick and x are that in this case.

[hedgefield]

Got around to doing an update to the interactive prototype with the approve/reject icon buttons, and a comment log in the top right.

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

The log is a bit barebones cause I just added it, but it keeps basic track of which comments are made. I also wonder if it should just be a sidebar - I used a popover, same as the info icon on the left of the toolbar, but it's not ideal-looking this way. And maybe some kind of indicator? Google Docs animates the comment flying into it when you resolve it. While looking at that I noticed they also do the single Resolve button which archives comments to the log.

[karmatosed]

@hedgefield this is heading in an awesome direction thanks for taking the considered route you have here. I wonder if the log could be made to look visually more similar to the library for the format? I am not sure unless there are a lot of comments for example it needs to be so large. What do you think of it growing?

[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! :)