Руководство по стилю

Это руководство по стилю поможет вам разобраться в целевой аудитории глоссария, структуре определений, стиле и требуемом уровне детализации.

Глоссарий Cloud Native придерживается стандартного руководства по стилю репозитория CNCF. Кроме того, он следует перечисленным ниже правилам:

  1. Используйте простой, доступный язык; избегайте технического жаргона и «модных» словечек.
  2. Избегайте разговорного стиля.
  3. Повествование должно быть последовательным и конкретным.
  4. Избегайте сокращений.
  5. Старайтесь не использовать страдательный залог.
  6. Стремитесь формулировать предложения в позитивной форме.
  7. Не используйте восклицательные знаки (допустимы только в цитатах).
  8. Не преувеличивайте.
  9. Избегайте повторов.
  10. Будьте лаконичны.

Целевая аудитория

Глоссарий предназначен как для специалистов, так и для людей, не знакомых с предметной областью. Пожалуйста, объясняйте термины простыми словами и не предполагайте наличия технических знаний у читателя. Подробнее об этом — ниже в разделе Определение.

Минимальное жизнеспособное определение

Мы стремимся к тому, чтобы любой человек мог легко разобраться в нативных облачных (cloud native) терминах. Поэтому уделяем особое внимание простоте. Используйте доступный язык с примерами, понятными каждому, кто использует технологию, одновременно сопровождая его минимальным необходимым набором технических подробностей. Не стоит экономить на контексте и примерах — в конце концов, они помогают читателю разобраться в той или иной концепции, — но если технические подробности не нужны для понимания, их лучше опустить. Не переусложняйте материал. Достаточно, чтобы читатель понял основную идею. При необходимости он сможет обратиться к другим ресурсам за подробностями. Мы не ставим перед собой цель превратить читателя в эксперта — это выходит за рамки данного глоссария.

Шаблон определения

Каждый термин глоссария хранится в markdown-файле и следует определенному шаблону:

---
title: 
status: 
category: 
---

## Описание

Краткое описание технологии или концепции.

## Проблема 

Несколько строк о проблеме.

## Решение

Несколько строк о том, как данная технология решает проблему, описанную выше.

Title

Лейбл title всегда должен находиться в верхней части шаблона определения, а его значение соответствовать формату для заголовков.

---
title: Definition Template

Status

Лейбл status идет после лейбла title. Он помогает понять, на какой стадии находится работа над определением.

Допустимые значения:

  • Completed (Завершена)
  • Feedback Appreciated (Приветствуется обратная связь)
  • Not Started (Еще не начиналась)

При этом всегда можно открыть Issue и внести правки в определение, работа над которым уже завершена. Все определения, над которыми ведется работа, имеют статус Feedback Appreciated (Приветствуется обратная связь).

---
title: Definition Template
status: Feedback Appreciated

Теги

После лейбла status идет лейбл tag. Ставьте только необходимые теги — это поможет сделать всю систему тегов осмысленной и, следовательно, полезной для читателя. Применение слишком большого количества тегов только ослабит их смысловое значение. Исключением является тег Fundamental — он указывает, что термин необходим для понимания других облачных концепций; при этом для большинства терминов, скорее всего, будет достаточно одного тега.

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

В настоящее время поддерживаются следующие теги:

  • Application
  • Architecture
  • Fundamental
  • Infrastructure
  • Methodology
  • Networking
  • Property
  • Security
---
title: Definition Template
status: Feedback Appreciated
tags: ["tag 1", "tag 2", ""]
---

Определение

Три раздела

Определения технологий и концепций включают три раздела:

  • Описание. Краткое и четкое описание того, о чем идет речь.
  • Проблема. Сосредоточьтесь на проблеме, а не на решении (его приберегите для следующего раздела). Избегайте упоминать термин, для которого дается определение. Фокусируйтесь на предпосылках, которые привели к разработке описываемой технологии/концепции.
  • Решение. Теперь можно вернуться к самому термину. Как именно он помогает решить проблему, описанную выше?

Обратите внимание, что характеристики/свойства не требуют отдельных разделов. Краткого определения будет достаточно.

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

Качество имеет первостепенное значение

Если PR будет принят, ваше описание станет официальным определением CNCF для этого термина (пока кто-то другой не дополнит его). Все определения должны соответствовать высоким стандартам CNCF — подходите к работе над ними размеренно, без спешки, ведь качество требует времени и усилий.

Изучите все досконально. Даже если вы уверены, что хорошо разбираетесь в предметной области, проверьте, правильно ли понимаете значение термина. Нередко бывает так, что оно оказывается искажено, не отражает всей сути или подразумевается совсем не то, что говорится. При изучении вопроса — особенно если вы не знакомы с термином на все 100% — пользуйтесь различными ресурсами. Многие определения носят односторонний характер, особенно если даются вендором. Определения в глоссарии должны быть независимыми от конкретного вендора и принятыми во всем мире.

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

Ссылайтесь на авторитетные источники. По возможности указывайте ссылки на надежные ресурсы, такие как проектная документация, запросы на обсуждение (RFD), стандарты и т.п. Обратите внимание, что нельзя ссылаться на материалы, публикуемые вендорами.

Стремитесь к простоте

Цель глоссария — объяснять сложные понятия простыми словами. Это на удивление непростая задача. Определения, скорее всего, будут неоднократно пересматриваться и дополняться. Составляя их, всегда помните о целевой аудитории. Старайтесь не использовать отраслевые жаргонизмы и “модные” словечки — избавиться от них иногда непросто, и приходится делать над собой усилие в поисках альтернатив.

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

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

Пример: посмотрите на раздел “Описание” в определении сервис-меша. В нем приведены ссылки на такие термины, как микросервис, сервис, надежность и наблюдаемость. Кроме того, используется реальный пример, проводящий параллель между сетевыми проблемами в среде микросервисов (то, с чем не сталкиваются рядовые пользователи) и проблемами с Wi-Fi-подключением (то, что доступно и понятно любому пользователю ноутбука). По возможности старайтесь приводить подобные примеры.

Начинайте с документа в Google Docs или в Word

Мы рекомендуем начать с документа в Google Docs или в Word. Запишите в него определение и свои мысли и оставьте их на несколько дней “дозревать”. Это поможет найти более простые и понятные формулировки. Кроме того, обязательно проверьте орфографию перед тем, как открыть PR.

Чтобы никто другой случайно не принял PR, пока вы работаете над ним, попросите закрепить Issue за собой (или создайте его при необходимости). Подробнее об этом — в документе Как внести свой вклад.

Прежде чем приступить к работе, ознакомьтесь с несколькими терминами из глоссария, чтобы получить представление о детализации и сложности описания, а также о том, когда уместно приводить примеры.

Процесс рассмотрения: чего ожидать

Обратите внимание, что в настоящее время сопровождением глоссария занимаются всего три человека, которые делают это в свободное от основной работы время. В некоторых случаях определения рассматриваются быстро, в других процесс может занять некоторое время — пожалуйста, наберитесь терпения. Если у вас возникли вопросы, свяжитесь с нами в Slack-канале #glossary или в канале локализации (о том, где и как их найти, читайте в документе Как внести свой вклад).

Наша цель — сделать Глоссарий Cloud Native передовым ресурсом. После того, как вы отправите PR, мы можем попросить вас внести в него несколько правок. Не расстраивайтесь — это обычная практика при совместной работе; так происходит со многими PR’ами. Общие усилия и открытое обсуждение помогут создать идеальное определение. Наградой за проделанную работу для вас станет благодарность читателей по всему миру.

Последнее изменение December 26, 2023: Review initial Russian content (8c3a264)