Как создавать записи в глоссарии и как на них ссылаться

Здесь вы можете прочитать о том, как создавать новые записи в глоссарии веб-документов MDN, как их оформлять, а также как правильно создавать ссылки на записи глоссария.

MDN глоссарий (словарь) – это место, где мы определяем все термины, жаргон и аббревиатуры, которые вы можете встретить, когда читаете о вебе и веб-разработке на MDN. Скорее всего, исчерпывающим этот словарь не станет никогда, ведь веб меняется постоянно. Вы можете помочь поддерживать глоссарий в актуальном состоянии, добавляя в него новые записи и исправляя ошибки. 

Делать вклад в словарь – это простой способ сделать веб понятнее для всех. Вам не нужно иметь высокий уровень технического мастерства для написания словарных статей. Статьи глоссария должны оставаться простыми и понятными.

Как писать записи

Ищете темы, которые нуждаются в записи глоссария? Посмотрите список незадокументированных терминов в конце целевой страницы глоссария. Щелкните любую из этих ссылок, чтобы начать новую страницу глоссария для элемента, на который вы нажали; затем выполните нижеуказанные действия.

Если же у вас уже есть идея для новой записи в глоссарии, просто нажмите на кнопку "Сделать новую запись в глоссарии" (см. ниже) так, чтобы она открылась в новой вкладке, а затем выполните нижеуказанные действия.

Шаг 1: Выберите термин, которому хотите дать определение

Первое, что нужно сделать, это выбрать термин, о котором писать. Если вы не знаете, какие термины нуждаются в определениях, вы можете проверить наш список предложений. Просто нажмите на термин и начните писать. Если вы уже авторизованы в системе, то вы попадете в Редактор MDN.

Шаг 2: Дайте краткое определение

Первый абзац любой страницы глоссария – это простое и краткое определение/описание термина (желательно не длиннее двух предложений). Удостоверьтесь, что любой, кто читает определение, сможет сразу понять определяемый термин.

Замечание: Пожалуйста, не копируйте определения из других источников (особенно из Википедии, поскольку её спектр лицензионных версий меньше, и, таким образом, несопоставим с MDN). Ваша запись должна быть уникальной, а не скопированной. 

Как создать хорошую запись глоссария

Если это необходимо, можете добавить несколько дополнительных абзацев, но будьте осторожны – так можно и увлечься, и вот вы уже пишете огромную статью. Написать полноценную статью – это прекрасно, но, пожалуйста, не помещайте ее в глоссарий. Если вы не уверены, где разместить свою статью, не стесняйтесь обратиться за помощью и обсудить это.

Вот несколько простых рекомендаций, которые стоит применять при написании записей в глоссарий:

  • Если для описания термина вы используете другие термины или аббревиатуры, то делайте ссылки и на их определения. Чаще всего, это будут простые ссылки на другие страницы глоссария (см. Как использовать макрос глоссария ниже). Для самых важных терминов, напрямую связанных с описываемым термином, лучше делать ссылку на основную статью MDN WebDocs по этой теме.
  • Используйте подходящие связанные термины (со ссылками) в вашей записи, но только если уверены, что это не затруднит восприятие. Наличие хорошей сети связанных, полезных ссылок может сделать страницу или набор страниц намного более простыми в использовании.
  • Подумайте о том, что бы вы ввели в поисковую систему, если бы хотели найти эту страницу. Попробуйте использовать все эти ключевые слова в записи, но постарайтесь сделать это так, чтобы запись при этом не утратила смысл, не стала слишком длинной или трудной для чтения.

Отредактируйте всплывающие подсказки

Как и в случае с большинством ссылок MDN, наведение курсора мыши на ссылку глоссария покажет краткое описание страницы (в данном случае краткое описание определения термина). По умолчанию подсказка представляет собой весь первый абзац статьи, но в большинстве случаев такое описание может оказаться слишком большим.

Вы можете сами указать фрагмент текста, который в дальнейшем будет использоваться как текст всплывающей подсказки при ссылке на вашу запись. Выберите одно или два предложения в записи, которые лучше всего описывают термин, а затем добавьте к ним стиль "SEO Summary" (резюме). Это действие не только создаст текст подсказки, но и определит текст, который будет отправлен в Google и другие поисковые системы, когда они запросят краткое резюме, описывающее содержимое страницы. Таким образом, вашу запись будет легче находить с помощью поисковиков.

Примечание: В идеале, резюме должно содержать около 150-160 символов. Лучше меньше, да лучше. 

Шаг 3: Добавьте ссылки

Заканчиваться запись в глоссарии всегда должна разделом "Узнать больше". Этот раздел должен содержать ссылки, которые помогут читателю подробнее изучить вопрос: узнать больше деталей, научиться использовать соответствующие технологии и так далее.

Мы рекомендуем сортировать ссылки по трем группам:

Общие знания
Ссылки, которые предоставляют информацию более общего характера, например, ссылка на Википедию – это хорошая отправная точка.

Технический справочник
Ссылки на более подробную техническую информацию, на MDN или в другом месте.

Узнать больше
Ссылки на учебные пособия, упражнения, примеры или любые другие материалы, которые помогают читателю научиться использовать технологию, стоящую за определенным термином.

Что делать, если у термина несколько значений

Иногда один и тот же термин может иметь разные значения в зависимости от контекста. Чтобы избежать возможных разночтений и путаницы, следуйте этим рекомендациям:

  • На основной странице записи, посвященной термину, должны быть перечислены все его возможные значения. Это делается с помощью макроса GlossaryDisambiguation.
  • Для каждого значения должна быть создана отдельная подстраница.

Пример:

У англоязычного термина signature как минимум три значения: одно в контексте безопасности, второе – подпись функции, и третье – подпись в контексте электронной почты. Вот как оформлена запись глоссария в этом случае:

  1. Основная страница Glossary/Signature – это страница с перечислением всех значений термина. Она оформлена с помощью макроса GlossaryDisambiguation.
  2. На подстранице Glossary/Signature/Security дано определение термина signature в контексте безопасности.
  3. Подстраница Glossary/Signature/Function посвящена значению "подпись функции".
  4. И, наконец, третья подстраница Glossary/Signature/Email посвящена тому, что такое подпись в контексте электронной почты.

Как использовать макрос {{Glossary}}

Глоссарий становится полезнее и используется чаще, когда к записям можно перейти по ссылкам из других документов. Чтобы обеспечить читателям такую возможность, используйте макрос Glossary:

Макрос Результат Примечание
{{Glossary("browser")}} browser

В случае, когда текст ссылки – это сам термин, то он и будет аргументом макроса (регистр значения не имеет).

{{Glossary("browser", "Web browser")}} Web browser Если хотите использовать другой текст ссылки, укажите его как второй аргумент.
{{Glossary("browser", "Web browser", 1)}} Web browser Если хотите, чтобы ссылка отображалась как стандартная ссылка, а не как всплывающая подсказка, то укажите 1 как третий аргумент.

Ссылки, созданные с помощью макроса {{Glossary}}, отображаются в виде всплывающей подсказки, содержащей соответствующий абзац глоссария, или SEO summary (как редактировать такие всплывающие подсказки, см. выше). 

Рекомендации по использованию макроса

Во многих случаях совершенно безопасно использовать макрос на MDN. Однако, есть несколько случаев, когда нужно использовать его с острожностью:

  • Если видите уже существующую (правильную, уместную) ссылку на какую-либо статью MDN, не редактируйте её с помощью макроса. Иными словами, не меняйте уже существующую ссылку на глоссарий-ссылку.
  • Внутри одного раздела статьи используйте не больше одного макроса {{Glossary}} для каждого определяемого термина. (Подсказка, как распознать разделы статьи: у каждого раздела всегда есть заголовок).