How to set the summary for a page

في هذه المقالة ، سنعرض كيفية تعيين ملخص تحسين محركات البحث (المعروف أيضًا بالوصف أو ملخصًا فقط) لمقالة على موقع مستندات ويب MDN. يستخدم الملخص بعدة طرق:

  •  يتم استخدام جوجل ومحركات البحث الاخرى للمساعدة على فهرسة الصفحات.
  • تعرض محركات البحث الملخص في صفحات نتائج البحث لمساعدة القراء على اختيار الصفحة الأكثر تطابقاً لاحتياجاتهم.
  • غالبًا ما تعرض قوائم MDN والصفحات المقصودة للموضوع الملخص أسفل عنوان المقالة ، ومرة أخرى لمساعدة المستخدمين في العثور على المعلومات التي يبحثون عنها.
  • تحتوي الروابط على MDN بشكل متكرر على تلميحات تحتوي على نص الملخص ، لتوفير نظرة سريعة للمستخدمين دون الحاجة إلى النقر على المقالة نفسها.

لذلك ، يجب أن يكون الملخص نصًا منطقيًا في سياق المقالة نفسها وكذلك عند تقديمه بمفرده في سياقات أخرى. يجب عليك أيضًا الاحتفاظ بدليل نمط كتابة MDN في الاعتبار أثناء كتابة نص الملخص.

الملخص الافتراضي

تعتمد الصفحات التي لا تحتوي أي ملخص على الملخص الافتراضي.
بشكل افتراضي يعتبر ملخص الصفحة هو أول قسم من الصفحة مكتوب ب 
لذلك من الممكن أي يكون الملخص عبارة عن نص وليس عنوان. 

هذا النص ليس الأفضل للاستخدام دائما ولكن ولبعض الأسباب المذكورة أدناه يعتبر أفضل استخدام.

  • النص الأول يعتبر شيء جانبي أو ملاحظة ما, ولا يقدم أي مراجعة كاملة للصفحة
  • أول نص مكتوب يعتبر نص محتوى ولكن لا يقدم مراجعة كاملة لمحتوى المقالة
  • النص طويل أو قصير للغاية

من الأفضل كتابة وتحديد ملخص الصفحة لضمان سهولة قراءة الملخصات واعتبارها مفيدة بقدر الإمكان.

Setting the summary

Let's look at how to go about setting a page's summary.

What is the task?
Marking the text within a page that should be used as its summary in other contexts; if appropriate text isn't already available, this task might include writing a small amount of appropriate text.
Where does it need to be done?
On pages that lack a summary, have a summary that isn't helpful, or have a summary that unnecessarily fails to meet recommended guidelines.
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. See the Guide to the MDN editor if you need information about using the 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

The summary is used in many different scenarios, including these:

  • As the description of the article on search results pages on MDN as well as on Google and other search engines.
  • As the description of the article in menus and topic landing pages on MDN itself.
  • In contextual tooltips when the user hovers the cursor over links to articles on MDN.

It's important to keep these scenarios in mind while composing a summary. In order to help ensure that the summary works well in all of these situations, please try to follow the guidelines below.

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

  • 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 example, and explains what technology is being covered, how the technology is being used, and that the article is a tutorial.
  • You can choose text from anywhere within any paragraph in the article, but it should ideally be within the first paragraph (or the second, in some cases). If the point of the article isn't made in those paragraphs, the introduction of the page probably needs rewriting.
  • The summary must still fit well within the context of the article's body, since it is in fact part of the article.
  • It's okay to have links to other pages within the summary. These are automatically removed before being given to search engines, and do not count against you. They're also removed before the summary is used as a tooltip. Links are not removed from the summary when used as a page description within menus and landing pages on MDN, which is really convenient as well.
  • 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.
  • To optimize the Search Engine Optimization (SEO) value gained from a summary, it should be no shorter than 150 characters long.
  • 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 dissuade people from clicking the link.
  • 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.

It can be a little tricky to write an summary that works well both for search engine result pages and within the article text itself, but currently MDN doesn't offer a way to create an SEO summary separate from the page content, so do the best you can.

See also