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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

Основная страница Glossary/Signature – это страница с перечислением всех значений термина. Она оформлена с помощью макроса GlossaryDisambiguation.
На подстранице Glossary/Signature/Security дано определение термина signature в контексте безопасности.
Подстраница Glossary/Signature/Function посвящена значению "подпись функции".
И, наконец, третья подстраница 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 (как редактировать такие всплывающие подсказки, см. выше).