Block descriptions: apply consistency in the descriptions, unifying the writing style using third person.

[cobianzo]

What?

This PR addresses issue #69475 by unifying the writing style used in block descriptions across the codebase.

This issue fixes the inconsistent use of verb tense (e.g. "Display" vs. "Displays") and phrasing patterns across blocks introduces minor but noticeable cognitive friction.

• Updated block descriptions from imperative form to third person, e.g.:
  • "Add a user’s avatar." → "Adds a user’s avatar."
• Applied this change in block.json files (e.g. paragraph, avatar, etc.), including blocks not currently active in WordPress.
• Also updated supporting documentation and test files to reflect the change in tone and guidance.
  • In particular Updated test/e2e/specs/editor/plugins/block-variations.spec.js where description strings changed. (playwright test has been ran and passed)

Why?

Consistent descriptions improve UX clarity and maintain a professional tone across the interface, especially for new users scanning the editor for functionality.

How?

• Using third-person present tense across all descriptions (e.g. "Displays", "Shows", "Adds").
• Aligning related documentation and tests with this updated tone.

Testing Instructions

Manual testing

• Insert every block in the editor. For every block, check the Block Description in Settings Sidebar.
• The description should not be presented in imperative form.
  • ❌ "Display a date archive of your posts."
  • ✅ "Displays a date archive of your posts."
  • ❌ "Add an image or video with a text overlay."
  • ✅ "Adds an image or video with a text overlay."
• The description can be presented in other forms, such as
  • ✅ "A calendar of your site’s posts."
  • ✅ "A form."
  • ✅ "The basic building block for forms."

Keyboard testing

• No changes affect the previous behaviour of keyboard shortcuts. The testings mentioned in the previous section can apply to a keyboard-shortcut use test.

Affected automated testing

• Run the playwright tests, in particular the ones that test the block descriptions:

  npm run test:e2e test/e2e/specs/editor/plugins/block-variations.spec.js
  

Review suggestions

This PR touches different areas:

• Block descriptions (UX copy) → cc @WordPress/gutenberg-core
• Documentation, when talking about the block descriptions (block-design.md, core-blocks.md) → cc @WordPress/gutenberg-docs
  Suggesting review of the original phrasing line by @sarahmonster.
• E2E tests (Playwright), updating tests to match the changes in the block descriptions → cc @WordPress/gutenberg-test
• Also tagging @mkaz for potential follow-up on image update in block-design.md. (image which remains out of date, referencing old description https://developer.wordpress.org/files/2022/01/block-descriptions-do.png)

Thanks!

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @cobianzo! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Type-related labels to choose from: [Type] Automated Testing, [Type] Breaking Change, [Type] Bug, [Type] Build Tooling, [Type] Code Quality, [Type] Copy, [Type] Developer Documentation, [Type] Enhancement, [Type] Experimental, [Type] Feature, [Type] New API, [Type] Task, [Type] Technical Prototype, [Type] Performance, [Type] Project Management, [Type] Regression, [Type] Security, [Type] WP Core Ticket, Backport from WordPress Core, Gutenberg Plugin.
• Labels found: Needs Copy Review, First-time Contributor.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[Infinite-Null]

Hi @cobianzo,
Thank you for your PR! 🙌 However, there’s already an existing PR that addresses this issue: #69478.
It’s always helpful to review and contribute to ongoing discussions on existing PRs. Your feedback there would be much appreciated! 😊

[talldan]

Thanks for contributing, but I think there should be more of an opportunity for copy and design contributors to add to the discussion in the issue.

I think that's especially the case since there was already an existing convention added in Documentation: Clarify block conventions for block descriptions, and that seems to have already been agreed upon by copy and design contributors at the time.

If you want to try a separate PR that fixes any existing descriptions that breaks the existing convention, then that might be an easier change.

[t-hamano]

Since a similar PR has already been submitted and further discussion is needed, let's close this PR.

@cobianzo We appreciate your efforts!

[cobianzo]

Hi @cobianzo, Thank you for your PR! 🙌 However, there’s already an existing PR that addresses this issue: #69478. It’s always helpful to review and contribute to ongoing discussions on existing PRs. Your feedback there would be much appreciated! 😊

Excellent, @Infinite-Null I see your PR now. Yes, I think I found some gotchas in the issue that might need to be addressed to your PR. I´ll add my comments there (#69478)!