We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

You can define the summary of a page on MDN, to be used in various ways, including in search engine results, in other MDN pages such as topical landing pages, and in tooltips. It should be text that makes sense both in the context of the page, and when displayed in other contexts, without the rest of the page content.

This summary is referred to by various names in different scenarios. It's also referred to as an SEO summary (in reference to being displayed along with the link's title on search result pages like on Google) or a description.

Setting the summary

A summary can be explicitly defined within a page. If it is not explicitly defined, then the first block that looks like text content is used, which is not always the best text for this purpose (especially if it's a side note of some sort).

What is the task?
Marking the text within a page that should be used as its summary in other contexts; this task might include writing appropriate text if needed.
Where does it need to be done?
On pages that lack a summary or have a less-than-great summary.
What do you need to know to do the task?
Ability to use the MDN editor; good English writing skills; enough familiarity with the topic of the page to write a good summary.
What are the steps to do it?
  • Pick a page on which to set the summary. If you already have one in mind, great! You can skip to step 2; otherwise, to find a page to fix:
    1. In the MDN documentation status page, click the link under Sections for a topic that you know something about (for example, HTML):
    2. On the topic's documentation status page, click the Pages header in the Summary table. This takes you to an index of all the pages in that topic section; it shows the page links in the left column, and the tags and summaries in the right column:
    3. Pick a page that is missing a summary, or that has a poor summary:
    4. Click the link to go to that page.
  1. Once on the page to which you wish to add a summary, click Edit to open the page in the MDN editor.
  2. Look for a sentence or two that works as a summary, even if taken out of context. If needed, edit the existing content to create or modify the text until you can select a sentence or two that make a good summary. See Crafting a good summary for help selecting or creating an appropriate summary.
  3. Select the text to be used as a summary.
  4. In the Styles widget of the editor toolbar, select SEO Summary. (In the page source, this creates a <span> element with class="seoSummary" around the selected text.)
  5. Save your changes with a revision comment. The comment is optional, but we encourage you to provide one. It makes it easier for other people to track the changes. Something like "Set SEO summary" is enough.

Crafting a good summary

In order to both capture a potential reader's attention and to serve as a good guide to users of a search engine, a page summary should meet certain guidelines.

Note: Unless otherwise specifically stated, these are guidelines, not hard, fast rules. While you should try hard to meet these guidelines, sometimes there are exceptions that can't be  avoided.

  • To optimize the SEO value gained from a summary, it should be no shorter than 150 characters.
  • Since a search engine result page (SERP) typically doesn't show more than 160 characters of the summary, you should avoid summaries longer than that. Having your text unceremoniously chopped off can harm its SEO value.
  • The summary should indicate both the topic and the type of page. "In this guide, we'll learn to use the Intersection Observer API to create responsive web apps that only update animations that are currently visible on screen." is 160 characters, for exmaple, and explains what technology is being covered, how the technology is being used, and that the article is a tutorial.
  • The summary should include an appropriate selection of key terms likely to be searched for by someone looking for information contained on the page. In the example case about the Intersection Observer API, those keywords include the API name, "animations", "visible", "responsive", and "web apps", possibly among others.

It can be a little tricky to write an SEO-friendly summary that works both for SERP purposes and on the page, but currently MDN doesn't offer a way to create an SEO summary separate from the page content, so do the best you can.

It might be tempting to write a great summary that doesn't work on page, then hide the summary inside a block with the "hidden" class on it. But this doesn't work, because search engines ignore text that's not visible to the user.

Think of the summary as being akin to the blurb on the back or inside the front cover of a book. This short text has to catch the reader's attention quickly and encourage them to read on.

See also

Document Tags and Contributors

Last updated by: Sheppy,