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

Вы читаете английскую версию этой статьи, так как пока нет перевода на данный язык. Помогите нам перевести эту статью!

MDN глоссарий это место где мы определяем все термины, жаргон и аббревиатуры используемые в документации и в коде. Делать вклад в словарь - это простой способ сделать для всех Web проще для понимания. Вам не нужно иметь высокий уровень технического мастерства для написания словарных записей по этому они должны оставаться простыми и понятными.

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

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

Если у вас есть идея для новой записи в глоссарии, просто нажмите кнопку, указанную ниже, на новой вкладке, а затем выполните действия нижеуказанные действия:

Шаг 1: Выберите термин для разъяснения

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

Шаг 2: Напишите краткое содержание

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

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

Напишите хороший заголовок глоссария

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

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

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

Размещайте всплывающие подсказки

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

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

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

Шаг 3: Расширьте с помощью ссылок

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

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

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

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

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

Предлагаемые условия

Итак, Вы хотите внести свой вклад, но Вы не знаете, какие термины должны быть определены? Вот список предложений. Выберите один из них и начните!

Работа со значениями

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

  • The term's main page must be a disambiguation page containing the GlossaryDisambiguation macro.
  • The term has subpages that define the term for a given context.

Let's illustrate that with an example. The term signature can have different meanings in at least three different contexts: security, function and email.

  1. The page Glossary/Signature is the disambiguation page with the GlossaryDisambiguation macro.
  2. The page Glossary/Signature/Security is the page defining a signature in a security context.
  3. The page Glossary/Signature/Function is the page defining a function signature.
  4. The page Glossary/Signature/Email is the page defining email signature.

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

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

Macro Result Note
{{Glossary("browser")}} browser When a text matches the term to be defined, just use the macro as is (it's case insensitive)
{{Glossary("browser", "Web browser")}} Web browser To display an alternative text, use the second argument to specify that text
{{Glossary("browser", "Web browser", 1)}} Web browser Specify 1 as an optional third argument to display the link as a regular link rather than a subtle hint

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

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

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

  • If a term is already linked to another part of MDN, leave it that way and do not use the {{Glossary}} macro.
  • Within an article section, use the {{Glossary}} macro only once for the same term (hint: a section always starts with a title).