enhance(seo): use meta description templates for web-api-* pages

[caugner]

Summary

(MP-1332)

Problem

For most pages, we use the first paragraph from the content as the meta description, but this isn't useful, because it doesn't explain what the page offers.

Solution

Use meta description templates to derive a meta description from the page title and sections instead.

---

How did you test this change?

Deployed to stage since 2024-08-16.

[Josh-Cena]

The ticket is not publically available. Do you have examples of pages with bad descriptions?

The content team generally tries to make the intro paragraph self-contained and descriptive so it's fit as meta description. This change seems to degrade the usefulness of the description for understanding the API conceptually from things like link preview cards or search results. Is it possible to at least stick the summary paragraph after this sentence?

[OnkarRuikar]

This is a double-edged sword. If the pages with bad summaries are fewer than the pages with good summaries, we'll miss out on good descriptions.

How about we augment the existing summary instead?

The Notification.permission is a static property. The permission read-only static property of the Notification interface indicates the current permission granted by the user for the current ...

The Window.localStorage is an instance property. The localStorage read-only property of the window interface allows you to access a Storage object for the Document's origin; the stored data ...

Above can be achieved using:

Suggested change

	case "web-api-instance-property":
	case "web-api-static-property":
	// "Learn about the Window.localStorage property, ..."
	// "Learn about the static Notification.permission property, ..."
	return `Learn about the ${doc.title.replace(/^(.*?): (.*?) (static )?property$/, "$3$1.$2 property")}, including ${contents}.`;
	case "web-api-instance-property":
	return `The ${doc.title.replace(/^(.*?): (.*?) property$/, "$3$1.$2")} is an instance property. ${doc.summary}`;
	case "web-api-static-property":
	return `The ${doc.title.replace(/^(.*?): (.*?) static property$/, "$3$1.$2")} is a static property. ${doc.summary}`;

[OnkarRuikar]

The ticket is not publically available.

Could you provide conversations/ gist of the Jira ticket in the OP's summary section? Also provide URL to the staged site.

• We can also implement enhance(seo): implement Breadcrumb, Article, and SearchAction structured data #11655 to enhance search result cards.

[caugner]

@Josh-Cena @OnkarRuikar The tl;dr is that meta descriptions serve a different purpose than the first paragraph, and should communicate to (search engine) users what the page offers, which is rarely the case for the first paragraph. For example, if you don't know MDN well, you won't know that the page contains code examples and information about browser compatibility. The new meta description templates communicate this.

We are confident that the change will improve our search engine performance, bringing more users to MDN, and we will measure the impact of this change to validate this.

[fiji-flo]

I talked with our content team and they are good with it for an experiment (still with the concern that if we have many hit's it will look rather odd). One ask was to keep the old description (summary) for the og:description.

My ask is to move it into the SSR as long as it's an experiment. It's less invasive and doesn't change the contract of the index.json for now. Once we know we want to keep this we have to move the templates to the content repo and make them translatable.

[Josh-Cena]

One ask was to keep the old description (summary) for the og:description.

That would be good. Yes my main concern is that the description is not a transparent implementation detail for search engines—it shows up in search results and link previews so we are taking information away from real readers.

I'm okay with the current idea of including more keywords like "parameters", "browser compatibility", etc.; my point is whether we can keep the summary too, like "Learn about the URL() constructor, including its parameters, exceptions, examples, specifications, browser compatibility. The URL() constructor returns a newly created URL object representing the URL defined by the parameters."

[fiji-flo]

@Josh-Cena do you think we should take the first sentence of the summary? (or whatever splitting at the first ". " gives us. Or just add the "full" summary.

[Josh-Cena]

Is there a downside to the description being "too long"? I'm inclined to just clip it at a certain length and add "...", but clipping at the first sentence may work too.

[caugner]

It actually isn't useful to add page content into the meta description, as Google will automatically show a snippet from the page content if it's more relevant/useful than the meta description. So the meta description is used as a fallback, if there is no relevant content snippet, including the first paragraph.

Note that the template-based descriptions are already about 160 characters on average, and longer descriptions are likely not shown in search results.

[Josh-Cena]

This is mostly about the link previews. If you think impact on search engine results is acceptable, let's only change og:description back to summary, if possible.

[Josh-Cena]

I would really appreciate if page type is in metadata.json (not sure if those two JSON files serve different purposes but I think metadata.json is a better fit). Would help with my own projects too.

[OnkarRuikar]

From my understanding the description doesn't affect the page ranking. It is only to be shown in search results. It is to convince seekers to click on our link. So we have to decide which one would entice seekers more, the intro section or the page description(learn about xyz).

Is there a downside to the description being "too long"? I'm inclined to just clip it at a certain length and add "...", but clipping at the first sentence may work too.

The search engine clips longer descriptions so no point in packing everything. We need a concise and attractive description.

as Google will automatically show a snippet from the page content if it's more relevant/useful than the meta description. So the meta description is used as a fallback

If the search engine doesn't like our new "Learn about the ..." it'll look at the content. We could use data-nosnippet attribute on all the top level divs that are not <div class="section-content"> to force google to derive the description from the intro section.

[fiji-flo]

I'll get this ported to rari so we don't don't break the experiment when we switch (I guess we need a few weeks / months to see the impact).