WordPress / WordPress/pattern-directory

Establish editorial rules for pattern title and description

Open
#572 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

[Component] Content & Guidelines
Dominant language
PHP
Stars
134
Forks
46
Avg merge
9h 4m
Merged PRs (30d)
19

Description

Describe the bug
The patterns title and description do have an impact on accessibility and usability of the WP user interface. They do have an impact also on the Patterns directory SEO. Their text should be meaningful and should avoid repetition. Also, the title and description used for the user interface are arguably ideal for SEO purposes.

I'm not sure this can be solved on the code side. Instead, I'd tend to think some editorial rules and best practices should be established in order to craft meaningful, useful, titles and descriptions. Also, it is worth considering rules for the patterns review process.

A few examples:

From an accessibility perspective:

This pattern title and description use the same text:

Title:       Three columns of text
Description: Three columns of text.

The only difference is a period at the end of the description.
When navigating through the list of patterns in the Inserter, screen readers announce both the title and the (visually hidden) description:

Screenshot 2023-03-29 at 11 46 16

That's redundant and just adds unnecessary noise.

For this other pattern, the first part of the description repeats the title text and then adds some more information:

Title:       Three columns with images and text
Description: Three columns with images and text, with vertical spacing for an offset look.

Also in this case, the repetition should be avoided, as the complete text announced by screen reader is noisy and redundant:

Screenshot 2023-03-29 at 11 18 01

Visually:

Worth noting that, when searching for a pattern in the inserter, the pattern preview fly-outs do actually show both the title and the description. In this scenario, displaying the same text twice looks unnecessary and feels like an unpolished UI:

Screenshot 2023-03-29 at 11 51 39

One more example of title and description with the same text:

Screenshot 2023-03-29 at 13 21 49

The repeated text looks off also when the description starts with the title text and then adds some more info:

Screenshot 2023-03-29 at 11 52 17

I don't have permissions to edit on the patterns directory but I'm guessing the description text comes from the textarea in the editor sidebar:

Screenshot 2023-03-29 at 10 50 01

Authors should take particular care when crafting the description text and always avoid repetition. Worth considering to clarify this point in the help text below the textarea or link to a page with some guidelines.

An example of better title and description is this pattern:

Title:       Three columns with title, description, and image
Description: Three columns. The first column has a title aligned to the bottom of the container, the second column has an italic description, and the third column has a portrait image.

In this case, the description actually describes the visual aspect of the pattern and it's meaningful enough, with little repetition.

Impact on SEO

To my understanding, the author-provided title and description are used also for the Opengraph og:title and og:description / meta description on the patterns directory. See for example this page: https://wordpress.org/patterns/pattern/three-columns-of-text/

<meta property="og:title" content="Three columns of text" />
<meta property="og:description" content="Three columns of text." />
<meta name="description" content="Three columns of text." />

That's less than ideal. The repetition seems, at best, useless and, at worst, suboptimal for SEO. Search engines will tend to use the provided description which just repeats the info provided in the title, e.g.:

Screenshot 2023-03-29 at 13 57 27

To Reproduce
Steps to reproduce the behavior:

  1. See the examples above.

Expected behavior
The pattern title and description to provide information that is actually useful for users.

  • Title: a concise, descriptive name of the pattern.
  • Description: a more detailed description of the pattern visual aspect.

Ideally, the information meant for SEO purposes should be provided separately. I'd recommend to consider to use two separate fields: SEO title and SEO description.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

  • OS: [e.g. iOS]
  • Browser [e.g. chrome, safari]
  • Version [e.g. 22]

Smartphone (please complete the following information):

  • Device: [e.g. iPhone6]
  • OS: [e.g. iOS8.1]
  • Browser [e.g. stock browser, safari]
  • Version [e.g. 22]

Additional context
Add any other context about the problem here.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the linked pattern examples, the pattern editor sidebar description textarea, and how the Patterns directory exposes title and description in its UI and metadata. Define editorial guidance that avoids repetition while describing the pattern clearly, and record whether separate SEO fields or review-process guidance is in scope. Done means the agreed rules and their intended location are documented.

Written by the indexing model from the issue text.

Assessment

Domain
accessibility, content, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.