Naming and Communication for Block Commenting in WP 6.9

[jeffpaul]

As we prepare to stabilize the Block Commenting feature for inclusion in WordPress 6.9, one important area that still needs clarity is how this feature should be named and communicated across the UI, documentation, and release materials. Establishing consistent naming now will prevent confusing or fragmented UI/UX, reduce rework later if strings/docs need to be updated, and help set clear expectations for the long-term direction of collaborative editing in WordPress.

The Problem

Currently, several terms are being used across issues, the roadmap, and discussions:

• Asynchronous collaboration
• Collaborative content creation
• Collaborative workflows
• Block commenting / Block level commenting
• Editorial comments
• Collaboration
• Multi-user block level commenting

This inconsistency could cause confusion for users and additional work for contributors if labels need to be revised later. We want to ensure the terminology is clear, consistent, and user-friendly before Beta 1 so that we have time to refine strings, docs, and messaging.

Options Under Consideration

A few naming directions have surfaced so far:

• Block Comments: Clear and descriptive at the technical level, but potentially confusing alongside the existing Comments Block.
• Editorial Comments: Emphasizes workflows for authors, editors, and teams.
• Discussions: Suggests multiple threaded conversations within a post or page context, but overlaps with how user comments function.
• Collaboration: Broad, aligns with the long-term vision of asynchronous/collaborative editing, but may be too vague for this specific feature.

Request for Feedback

I would appreciate input from the community on:

1. Which naming direction feels most appropriate and intuitive to end users?
2. Should the name differ between the API/feature level and the UI label shown to authors/editors?
3. How should this feature be referenced in user-facing areas (About page, documentation, announcement posts)?

Please share your feedback, preferences, and rationale so we can move toward consensus ahead of WordPress 6.9 Beta 1.

[jeremyfelt]

My gut reaction to "Block Comments" is that it sounds like a front-end feature. Comments already exist in the post context and it implies there is now block-level commenting on the post.

Editorial Comments seems more accurate. In theory these could expand out to the page level in the future (e.g. discussion on the page's slug or a piece of meta), so attaching the name to the editorial process rather than blocks makes sense to me.

I'd prefer the naming to be consistent in code, UI, and documentation as much as possible.

[talksina]

I agree with the user above: editorial comments is the most suitable explanation. Should be clear for accessibility label as well

[slam-campup]

In addition, Googling for "Block Comments" is just going to return pages about how to block commenting.

[eirichmond]

It feels like “Editorial Comment” makes more sense but “editorial” sounds a bit corporate. Most WordPress users would probably find “Content” more relatable and obvious, so maybe “Content Comment” works better, it is content after all.

[talksina]

"reply to current content"? As far as I know, this functionality is like GoogleDoc's feature which allows collaborators to leave a written feedback to content, am I right? In Google doc's case it's called "comments" because it's the only one available. But here on WordPress "comment" is used for front-end UI. Even "discussions" might be quite good IMHO.

…

Message ID: <WordPress/gutenberg/repo-discussions/72014/comments/14567998@ github.com>

[Otto42]

I'm just now reading about this feature, and I assume it will not be used for a front end display data. This is for comments by collaborators collaborating with each other. Therefore, you should avoid the use of the word "comments" all together. Comments has an existing meaning in WordPress, and overloading it with an extra feature that is not user visible is not a good idea. Maybe "editorial notes" or something like that instead.

[jeffpaul]

So on thing that has come up is that there's a not unreasonable future state where this same collaboration could be left on the frontend of a site via logged in users, as well as perhaps on previews, so worth considering that as folks provide feedback on naming options.

[mindctrl]

Since frontend display is under consideration for the future, I'm more inclined to agree with avoiding "comments". Otherwise when discussing with teammates and someone says "Did you see the comments on <post>?"... "Which comments? Editorial comments or post/public comments?"

Editorial Notes sounds good, and could be shorted in UI as Notes, Add a Note, Update Note, Delete Note, etc.

[JosVelasco]

Editorial comments are still comments. Content comments are still comments. The context helps to understand what comments inside the Editor are for, so, in my opinion, there is no confusion in simply referring to them as block comments or comments.

Many design and editing platforms refer to them as comments; I think we should use that simple name.

[hanneslsm]

My vote also goes for just comments as the overall name.
But "editorial comments" could be used in descriptive texts.

By the way, it wouldn't hurt if we would add a "privacy note" to the comments panel to make the context even more clear. Quick mockup:

[jasmussen]

An earlier term proposed for this was "Annotations", going back to when this was referred to as "the Annotation API".

[jmccall75]

Annotation suggests additional information for a reader, explanatory information. They are a subset of the more general term "comment." For example, a all footnotes are types of annotation and a form of comment. Not all comments are annotations.

In this context, very few comments would count as annotations.

[aaronjorbin]

Which naming direction feels most appropriate and intuitive to end users?

In an attempt to avoid picking a specific color for the bikeshed (which should be green, but that's a digression), I think it's important to layout the goals of the name. In my eyes, the name selected should:

1. Be as short of a name as possible in order to make it easier for modifiers to fit in the UI.
2. Avoid using phrases or words that could be confused with other existing features

Based on that, some of the suggestions that I've seen which seem best are:

1. Annotations
2. Notes
3. Discussions

Should the name differ between the API/feature level and the UI label shown to authors/editors?

In a perfect world, there would be no difference or very little difference. That said, since these are going to use comments under the hood, I could image there will be pieces (especially at first) that will not be 1:1.

How should this feature be referenced in user-facing areas (About page, documentation, announcement posts)?

I think this is where things such as "Editorial Comments" or "Content Comments" could come in handy. I'm thinking an about page that says something like:

Collaberate With Annotations Annotations allow you to leave editorial comments and asyncronously collaberate in the block editor with other users on your site.

[paaljoachim]

I was actually going to suggest Notes.
I did a search for Notes plugin WordPress and came across this: https://wordpress.com/plugins/browse/notes
and https://wordpress.org/plugins/noted/
As well as this general overview of Notes plugins.
https://blog.eazyplugins.com/wordpress-notes-plugin/

I am adding the above links as I am thinking one can compare the features of Block Commenting compared to some of the above plugins.

[jmccall75]

Notes would be my second preference, after "comment." Like "comment," it's simple and intuitive. Because of the unfortunate blogging-platform baggage WP keeps around, "notes" may actually be slightly better.

[jmccall75]

Keep it simple and just call it Comments. In dot-org documentation and the codebase itself, you can call them "Editorial Comments" to distinguish them from blog-post comments but in the Block Editor, "Comment" is simple, familiar, and intuitive.

• "Add a Comment"
• "Remove Comment"
• "Reply to Comment"
• "Show Comments"
• "Hide Comments"
• "Enable Comments"
• "Disable Comments"

Users will immediately understand those phrases, mostly because they've seen exactly the same wording and functionality in so many other applications.

Please don't call them "Block Comments." First, they are not comments on blocks. They are comments on content. And second, as someone who works with content editors on a daily basis, "block" is already super unfamiliar and confusing to first-time WordPress users--or, rather, first time block editor users. It is easy enough to explain but it is NOT intuitive or even logical outside the context of coding/HTML.

Also, if you're worried about the confusion between blog-like comments and editorial comments, two thoughts:

1. The only place this potential confusion matters is in the documentation and codebase. Adding "editorial" in those contexts is enough to distinguish the two forms of comments. Any conceptual overlap for content editors is a good thing since, well, post comments and editorial comments are basically the same thing in different contexts.
2. Who the heck still uses post comments, other than as a way to shoehorn in "reviews" and similar not-really-a-comment functionality? The more, and more quickly, we move away from WP's beginnings as a blogging platform, the better for all types of users. For many users, if not most, that blogging background is little more than an albatross around our necks. This is doubly true for developers.

[tyxla]

We've been referring to this feature as "Comments" or "Inline Comments" originally (see the 2023 workflows post), and I'm personally still fine with that terminology. That said, I can see how it could become confusing, particularly around whether these appear on the frontend or if they're connected to the existing WordPress commenting system.

The key ideas we want to preserve are:

• It's about discussing and commenting on content at a block level.
• It should be clear that this is an admin/editor-only feature, not visible on the frontend.

Names like "Block Discussions", "Block Comments", or "Block Threads" do a good job emphasizing collaboration, but they don't really convey the "admin-only" aspect, which feels like a significant gap we need to account for.

Something like "Block Notes" might work better. It keeps the connection to the block context, but also implies something private, similar to how presenter notes work in slides: visible to the presenter, but not to the audience.

Alternatively, "Editorial Comments" or "Editorial Notes" could also capture the intent well. They express that this feature is meant for internal use by editors and administrators, without necessarily needing to include "Block" in the name, since the block-level detail is more of a technical implementation than a user-facing concept.

[jmccall75]

Editorial comments/notes seems perfect, imo.

[slam-campup]

Or event Editor Notes, since it's primarily used in the WordPress Post Editor.

[annezazu]

👋🏼 Hey folks. Love seeing all of the discussion around this and, in order to get a decision in place for 6.9, I've reviewed the feature and proposed names with @m, @mtias, and @4thhubbard (the triple M's). The consensus and decision is to move forward with calling it "Notes". This addresses needing to distinguish it from already known comment functionality in WordPress, making it easier to document and communicate the feature going forward. It also ensures that when it opens up beyond block level, the name can remain.

Thank you to all the hard work on this feature and for everyone who so thoughtfully shared their perspectives.

[jeffpaul]

Perfect, thanks for helping get to a resolution here @annezazu!

[paaljoachim]

Great! As you said "Notes" clearly distinguishes from the comment functionality in WordPress. That was also my thought. As it really needs to create a clear separation from the comments feature.