Skip to content

Blocks descriptions use inconsistent verb person and pattern #69475

@afercia

Description

@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:

Image

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.

  • Yes

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

  • Yes

Please confirm which theme type you used for testing.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Needs Copy ReviewNeeds review of user-facing copy (language, phrasing)Needs Design FeedbackNeeds general design feedback.[Package] Block library/packages/block-library[Status] In ProgressTracking issues with work in progress[Type] BugAn existing feature does not function as intended[Type] CopyIssues or PRs that need copy editing assistance

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions