Blocks descriptions use inconsistent verb person and pattern

[afercia]

Description

All the blocks come with their own name and description. One of the main places where the description is shown in the UI is in the 'block card' at the top of the Block settings panel.

Many of these description use an inconsistent verb person, the most evident is Display vs. Displays (third person).

There's many other verbs in use with the same inconsistency. Other descriptions use a completely different pattern. A few screenshots:

While minor, this introduces inconsistency and unnecessary cognitive load with understanding the difference between the different wordings.

At the very least I'd suggest to:

• Fix the most evident Display vs. Displays case.
• I'd suggest to also use third person for all the descriptions that start with a verb. -To be discussed: whether other patterns like The author name. or A calendar of your site’s posts. should be changed to use a sentence that starts with a verb.

Some of the other starting verbs I found:

• Add
• Contains
• Create
• Describe
• Embed
• Gather
• Give
• Hide and show
• Insert
• Introduce
• Prompt
• Provide
• Reuse
• Separate
• Set
• Show
• Summarize
• Use

Other patterns examples:

• The author name.
• A calendar of your site’s posts.

Step-by-step reproduction instructions

• Search in the codebase for "description" (including the quotes) limiting the search to the /packages/block-library directory.
• Observe the inconsistencies in the descriptions.

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

• [x] Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

• [x] Yes

Please confirm which theme type you used for testing.

• [ ] Block
• [ ] Classic
• [ ] Hybrid (e.g. classic with theme.json)
• [ ] Not sure

[aditya-raj-panjiyara]

Hi @afercia is this issue still open?

[cobianzo]

Hi @aditya-raj-panjiyara and @afercia . I am a senior WP developer with years working in WP VIP environments.
I'd like to start collaborating with the core, and this seems to be a perfect task. Can I take it over and create a PR? I'm in slack as well with same nickname , cobianzo

[talldan]

It'd be great to see inconsistencies fixed, but I think this issue needs a bit more discussion before changing the descriptions of all the blocks.

There was an existing convention introduced in Documentation: Clarify block conventions. It seems like that was agreed upon by several design and copy contributors (the discussion was mostly in this PR - Group block: Updated the block description). It'd be good to see a similar level of discussion before changing all the copy and naming conventions again.

[Infinite-Null]

Thanks for the context, @talldan. I’ll wait for further discussion on the issue and update the PR to reflect the points raised, ensuring it stays consistent with the established conventions.

[hanneslsm]

What design feedback is needed? I'd say as long we have consistency across all blocks and the descriptions are not too long, design (UI and UX) gets a pass.

[hanneslsm]

Regarding copy, we had a extensive discussion on https://github.com/WordPress/gutenberg/issues/52392#issuecomment-1906203755 how to phrase things. It's a very different context (warning modal on removing an important block), but we ended up with

• using your to personalize that it's your post and page but not to address someone directly (e.g. you should not remove this block)
• making it clear what effect the user's action has. ( This will lead to …)
• making it clear what the block does. (It displays content on this template)

---

At the very least I'd suggest to: Fix the most evident Display vs. Displays case.

Agreed 👍

-To be discussed: whether other patterns like The author name. or A calendar of your site’s posts. should be changed to use a sentence that starts with a verb.

Yes, I think so to ensure consistency.

[Sayonigithub]

Hi! I’d like to work on this issue. Could you please assign it to me?

[Infinite-Null]

Hi @Sayonigithub, Thanks for looking into this! 🙌 But, there’s already a pull request open for this issue: #69478. If you’d like, feel free to review it and share your thoughts!

[BommiYaswanth]

“Hi! I'm a first-time contributor. Can I take this up?”

[Mamaduka]

I've removed the Good First Issue label. The issue already has a PR in progress.