Руководство по стилю документации YDB

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

Основные принципы

  • Понимание целевой аудиторией:
    • Перед началом работы над новой статьёй или улучшением существующей уделите время на определение её целевой аудитории. Учитывайте их конкретную роль (разработчики приложений, DevOps-инженеры, инженеры по безопасности и т.д.), технический опыт и знакомство с темой статьи и YDB в целом.
    • Убедитесь, что текст понятен целевой аудитории статьи.
  • Чёткий язык:
    • Используйте простой, понятный язык, который напрямую передаёт мысли автора.
    • Избегайте сложных фраз, которые могут быть трудны для неносителей языка.
    • Избегайте жаргона и сленга, если они не являются общепринятыми в отрасли.
  • Последовательная терминология:
    • Для каждого необычного термина в статье убедитесь, что первое использование содержит ссылку на объяснение:
      • Для терминов, специфичных для YDB, ссылайтесь на Глоссарий YDB. Если в глоссарии перечислено несколько синонимов термина, используйте основной из заголовка глоссария. Если запись в глоссарии отсутствует, добавьте её.
      • Для общих терминов, которые могут быть незнакомы некоторым читателям, ссылайтесь на их страницу в Википедии или аналогичном общеизвестном источнике. Избегайте ссылок на блоги, социальные сети или случайные сторонние статьи.
    • Если в тексте есть аббревиатура, при первом появлении в статье напишите её полностью и явно покажите аббревиатуру в скобках. Например, Structured Query Language (SQL).
  • Структурированное содержание:
    • Каждая статья должна иметь только одну цель для достижения читателем. Если текст преследует несколько целей, вероятно, его нужно разделить на несколько статей. Если возможно, явно укажите эту цель в начале статьи и продемонстрируйте её достижение в конце.
    • Каждая статья должна следовать только одному жанру. Если это не так, то вероятно её нужно разделить на несколько статей.
    • Организуйте статьи с помощью заголовков, подзаголовков, списков, заметок, таблиц и блоков кода, чтобы помочь читателям быстро ориентироваться в информации.
    • Следуйте общей структуре документации при создании новых статей.

Тон повествования

  • Разговорный. Стремитесь к тону, который ощущается как объяснение концепций опытным другом в доступной манере.
  • Дружелюбный и уважительный. Сохраняйте баланс профессионализма и дружественной теплоты.
  • Инклюзивный язык. Пишите нейтрально и уважительно, избегая предвзятого или исключающего языка.
  • Контекстно-зависимый. Прдстраивайте тон текста в зависимости от типа контента. Для практических руководств будьте более ободряющими; для справочного материала будьте более точными и краткими.
  • Активный залог. Предпочитайте активные конструкции для обеспечения ясности и непосредственности, облегчая следование инструкциям.

Специфика языка

Убедитесь, что текст следует правилам своего языка без опечаток, грамматических, пунктуационных или орфографических ошибок. Кроме того, следуйте этим специфичным для YDB правилам.

Только для английского

Только для русского

  • Используйте ё где это уместно.
  • Используйте кавычки-ёлочки (« и »).
  • Используйте — (en dash) для тире.
  • Используйте точку с запятой для маркированных и нумерованных списков где это уместно, т.е. для всех элементов, кроме последнего, если элементы не содержат нескольких предложений.
  • Не используйте заголовочный регистр для заголовков.

Форматирование и структура

  • Чёткая иерархия. Используйте заголовки и подзаголовки для определения разделов и облегчения просмотра документа.

  • Списки и маркеры. Используйте маркеры или нумерованные списки для разбивки шагов, функций или рекомендаций.

  • Визуальные выделения. Если есть важное предупреждение, информация или совет, выделите их с помощью тега {% note info %} ... {% endnote %}. Для небольших выделений по тексту используйте жирный или курсив, но в меру.

  • Код и примеры. При включении кода используйте правильное выделение синтаксиса, форматирование и комментарии для обеспечения читаемости. Показывайте примеры вывода для запросов и CLI-команд. Используйте блоки кода для всего, что может появиться в консоли или IDE, но не для визуальных выделений.

  • Ссылки.

    • Предоставляйте ссылки на релеватные ресурсы или дополнительную документацию.
    • Ссылки внутри документации всегда должны включать суффикс .md и быть относительными (то есть без префикса https://ydb.tech); в противном случае проверка согласованности ссылок не работает, и со временем они начнут вести к ошибкам 404.
    • Вместо повторения заголовка целевой статьи для внутренних ссылок используйте [{#T}](path/to/an/article.md).

  • Без копирования. Если ссылок не достаточно и часть информации должна отображаться в документации более одного раза, создайте отдельный файл Markdown в папке _includes, затем добавьте его во все необходимые места через {% include [...](_includes/path/to/a/file.md) %} вместо дублирования контента копированием и вставкой.

  • Стиль синтаксиса Markdown. Документация YDB использует автоматический линтер для файлов Markdown. Обратитесь к .yfmlint для актуального списка применяемых правил.

  • Использование переменных. Документация YDB имеет конфигурационный файл presets.yaml, который перечисляет переменные для предотвращения опечаток или условного скрытия контента. Используйте эти переменные где это уместно, особенно YDB вместо YDB.

  • Диаграммы. Используйте встроенные диаграммы Mermaid, если это возможно. Если используется сторонний инструмент для диаграмм, сохраните исходный файл в ту же папку _assets рядом с изображением для будущих правок. Убедитесь, что диаграммы хорошо выглядят как в светлой, так и в тёмной теме.

  • Правильное размещение статей. Новые статьи должны быть правильно размещены в соответствии со структурой документации.

  • Консистентность жанра. Статьи не должны смешивать несколько жанров, и жанр должен соответствовать месту статьи в структуре документации.

Интеграция документации

  • Перекрёстные ссылки. Добавляйте ссылки на все релевантные существующие страницы документации, либо по ходу текста, либо в разделе «См. также» в конце.
  • Обратные ссылки. Обновляйте релевантные существующие статьи ссылками на новые статьи.
  • Включение в индекс. Упоминайте все статьи в оглавлении (toc_i.yaml или toc_p.yaml) и index.md их папки.
  • Ссылки на исходный код. Ссылайтесь напрямую на исходные файлы на GitHub когда это уместно. Если цель ссылки может значительно измениться со временем, используйте ссылку на конкретный коммит или стабильную ветку.
  • Ссылки на глоссарий:
    • Когда термин, специфичный для YDB, упоминается в статье впервые, сделайте его кликабельной ссылкой на соответствующую запись глоссария.
    • Если есть отдельная подробная статья по той же теме, что и термин глоссария, добавьте ссылку на неё из описания термина глоссария.

Использование и гибкость

  • Рекомендации, а не жёсткие правила. Это руководство по стилю предлагает рекомендации для улучшения ясности и последовательности, но допускает гибкость, когда отклонения приносят пользу контенту.
  • Дополнительные ресурсы. Авторам рекомендуется консультироваться с внешними руководствами по стилю (например, The Chicago Manual of Style, Merriam-Webster) при неоднозначных ситуациях.
  • Обновления. Это руководство эволюционирует со временем вместе с остальным контентом. Если вы часто вносите вклад в документацию YDB, периодически возвращайтесь сюда, чтобы ознакомиться с обновлениями.

Чего следует избегать

  • Жаргона и сленга.
  • Использования «мы».
  • Шуток и другого эмоционального контента.
  • Чрезмерно длинных предложений.
  • Нерелевантных тем и отсылок, таких как культура, религия или политика.
  • Излишне подробных деталей реализации (кроме Разработка YDB, Список изменений YDB Server и Видеозаписи).
  • Повторного использования стороннего контента без письменного разрешения или совместимой открытой лицензии, явно разрешающей это.
  • HTML внутри Markdown, кроме как для обхода отсутствующих визуальных стилей.

См. также

Предыдущая
Процесс ревью
Следующая
Структура