--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ydb.tech/docs/en/contributor/documentation/style-guide.md?version=v25.3 - https://ydb.tech/docs/ru/contributor/documentation/style-guide.md?version=v25.3 - href: ru/contributor/documentation/style-guide.md type: text/markdown title: Markdown version - href: ../../llms.txt type: text/markdown title: llms.txt sourcePath: ru/core/contributor/documentation/style-guide.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Руководство по стилю документации YDB Руководство по стилю документации YDB разработано, чтобы помочь авторам создавать понятную, последовательную и удобную для разработчиков документацию. ## Основные принципы {#core-principles} - **Понимание целевой аудиторией:** - Перед началом работы над новой статьёй или улучшением существующей уделите время на определение её целевой аудитории. Учитывайте их конкретную роль ([разработчики приложений](https://ydb.tech/docs/ru/dev/index.md?version=v25.3), [DevOps-инженеры](https://ydb.tech/docs/ru/dev/index.md?version=v25.3), [инженеры по безопасности](https://ydb.tech/docs/ru/security/index.md?version=v25.3) и т.д.), технический опыт и знакомство с темой статьи и YDB в целом. - Убедитесь, что текст понятен целевой аудитории статьи. - **Чёткий язык:** - Используйте простой, понятный язык, который напрямую передаёт мысли автора. - Избегайте сложных фраз, которые могут быть трудны для неносителей языка. - Избегайте жаргона и сленга, если они не являются общепринятыми в отрасли. - **Последовательная терминология:** - Для каждого необычного термина в статье убедитесь, что первое использование содержит ссылку на объяснение: - Для терминов, специфичных для YDB, ссылайтесь на [Глоссарий YDB](https://ydb.tech/docs/ru/concepts/glossary.md?version=v25.3). Если в глоссарии перечислено несколько синонимов термина, используйте основной из заголовка глоссария. Если запись в глоссарии отсутствует, добавьте её. - Для общих терминов, которые могут быть незнакомы некоторым читателям, ссылайтесь на их страницу в Википедии или аналогичном общеизвестном источнике. Избегайте ссылок на блоги, социальные сети или случайные сторонние статьи. - Если в тексте есть аббревиатура, при первом появлении в статье напишите её полностью и явно покажите аббревиатуру в скобках. Например, Structured Query Language (SQL). - **Структурированное содержание:** - Каждая статья должна иметь только *одну* цель для достижения читателем. Если текст преследует несколько целей, вероятно, его нужно разделить на несколько статей. Если возможно, явно укажите эту цель в начале статьи и продемонстрируйте её достижение в конце. - Каждая статья должна следовать только одному [жанру](https://ydb.tech/docs/ru/contributor/documentation/genres.md?version=v25.3). Если это не так, то вероятно её нужно разделить на несколько статей. - Организуйте статьи с помощью заголовков, подзаголовков, списков, заметок, таблиц и блоков кода, чтобы помочь читателям быстро ориентироваться в информации. - Следуйте общей [структуре документации](https://ydb.tech/docs/ru/contributor/documentation/structure.md?version=v25.3) при создании новых статей. ## Тон повествования {#voice} - **Разговорный.** Стремитесь к тону, который ощущается как объяснение концепций опытным другом в доступной манере. - **Дружелюбный и уважительный.** Сохраняйте баланс профессионализма и дружественной теплоты. - **Инклюзивный язык.** Пишите нейтрально и уважительно, избегая предвзятого или исключающего языка. - **Контекстно-зависимый.** Прдстраивайте тон текста в зависимости от типа контента. Для практических руководств будьте более ободряющими; для справочного материала будьте более точными и краткими. - **Активный залог.** Предпочитайте активные конструкции для обеспечения ясности и непосредственности, облегчая следование инструкциям. ## Специфика языка Убедитесь, что текст следует правилам своего языка без опечаток, грамматических, пунктуационных или орфографических ошибок. Кроме того, следуйте этим специфичным для YDB правилам. ### Только для английского - Используйте [последовательную запятую](https://en.wikipedia.org/wiki/Serial_comma) где это уместно. - Используйте [заголовочный регистр](https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D0%B3%D0%BE%D0%BB%D0%BE%D0%B2%D0%BE%D1%87%D0%BD%D1%8B%D0%B9_%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80) для заголовков, предпочтительно следуя правилам [Chicago Manual of Style](https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D0%B3%D0%BE%D0%BB%D0%BE%D0%B2%D0%BE%D1%87%D0%BD%D1%8B%D0%B9_%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80#Chicago_Manual_of_Style). В качестве кавычек в тексте используйте простые двойные кавычки ("). ### Только для русского - Используйте `ё` где это уместно. - Используйте [кавычки-ёлочки](https://en.wikipedia.org/wiki/Guillemet) (`«` и `»`). - Используйте `—` (en dash) для тире. - Используйте точку с запятой для маркированных и нумерованных списков где это уместно, т.е. для всех элементов, кроме последнего, если элементы не содержат нескольких предложений. - *Не* используйте [заголовочный регистр](https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D0%B3%D0%BE%D0%BB%D0%BE%D0%B2%D0%BE%D1%87%D0%BD%D1%8B%D0%B9_%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80) для заголовков. ## Форматирование и структура - **Чёткая иерархия.** Используйте заголовки и подзаголовки для определения разделов и облегчения просмотра документа. - **Списки и маркеры.** Используйте маркеры или нумерованные списки для разбивки шагов, функций или рекомендаций. - **Визуальные выделения.** Если есть важное предупреждение, информация или совет, выделите их с помощью тега `{% note info %} ... {% endnote %}`. Для небольших выделений по тексту используйте **жирный** или *курсив*, но в меру. - **Код и примеры.** При включении кода используйте правильное выделение синтаксиса, форматирование и комментарии для обеспечения читаемости. Показывайте примеры вывода для запросов и CLI-команд. Используйте `блоки кода` для всего, что может появиться в консоли или IDE, но не для визуальных выделений. - **Именование файлов.** Используйте дефисы вместо подчёркиваний для пробелов в именах новых файлов и папок (например, `new-folder/new-file.md` вместо `new_folder/new_file.md`). Тем не менее, подчёркивания допустимы в ключевых словах, которые должны писаться именно с подчёркиваниями, например в названиях настроек. - **Ссылки.** - Предоставляйте ссылки на релеватные ресурсы или дополнительную документацию. - Ссылки внутри документации всегда должны включать суффикс `.md` и быть относительными (то есть без префикса `https://ydb.tech`); в противном случае проверка согласованности ссылок не работает, и со временем они начнут вести к ошибкам 404. Внутренние ссылки не должны содержать параметры вида `?version=...`, `?revision=...` или аналогичные. - Вместо повторения заголовка целевой статьи для внутренних ссылок используйте `[{#T}](path/to/an/article.md)`. - **Без копирования.** Если ссылок не достаточно и часть информации должна отображаться в документации более одного раза, создайте отдельный файл Markdown в папке `_includes`, затем добавьте его во все необходимые места через `{% include [...](_includes/path/to/a/file.md) %}` вместо дублирования контента копированием и вставкой. - **Стиль синтаксиса Markdown.** Документация YDB использует автоматический линтер для файлов Markdown. Обратитесь к [.yfmlint](https://github.com/ydb-platform/ydb/blob/main/ydb/docs/.yfmlint) для актуального списка применяемых правил. - **Использование переменных.** Документация YDB имеет конфигурационный файл [presets.yaml](https://github.com/ydb-platform/ydb/blob/main/ydb/docs/presets.yaml), который перечисляет переменные для предотвращения опечаток или условного скрытия контента. Используйте эти переменные где это уместно, особенно `YDB` вместо `YDB`. - **Диаграммы.** Используйте встроенные диаграммы [Mermaid](https://github.com/diplodoc-platform/mermaid-extension), если это возможно. Если используется сторонний инструмент для диаграмм, сохраните исходный файл в ту же папку `_assets` рядом с изображением для будущих правок. Убедитесь, что диаграммы хорошо выглядят как в светлой, так и в тёмной теме. - **Правильное размещение статей.** Новые статьи должны быть правильно размещены в соответствии со [структурой документации](https://ydb.tech/docs/ru/contributor/documentation/structure.md?version=v25.3). - **Консистентность жанра.** Статьи не должны смешивать несколько [жанров](https://ydb.tech/docs/ru/contributor/documentation/genres.md?version=v25.3), и жанр должен соответствовать месту статьи в структуре документации. ### Интеграция документации - **Перекрёстные ссылки.** Добавляйте ссылки на все релевантные существующие страницы документации, либо по ходу текста, либо в разделе «См. также» в конце. - **Обратные ссылки.** Обновляйте релевантные существующие статьи ссылками на новые статьи. - **Включение в индекс.** Упоминайте все статьи в оглавлении (`toc_i.yaml` или `toc_p.yaml`) и `index.md` их папки. - **Ссылки на исходный код.** Ссылайтесь напрямую на исходные файлы на GitHub когда это уместно. Если цель ссылки может значительно измениться со временем, используйте ссылку на конкретный коммит или стабильную ветку. - **Ссылки на глоссарий:** - Когда термин, специфичный для YDB, упоминается в статье впервые, сделайте его кликабельной ссылкой на соответствующую запись глоссария. - Если есть отдельная подробная статья по той же теме, что и термин глоссария, добавьте ссылку на неё из описания термина глоссария. ## Использование и гибкость - **Рекомендации, а не жёсткие правила.** Это руководство по стилю предлагает рекомендации для улучшения ясности и последовательности, но допускает гибкость, когда отклонения приносят пользу контенту. - **Дополнительные ресурсы.** Авторам рекомендуется консультироваться с внешними руководствами по стилю (например, The Chicago Manual of Style, Merriam-Webster) при неоднозначных ситуациях. - **Обновления.** Это руководство эволюционирует со временем вместе с остальным контентом. Если вы часто вносите вклад в документацию YDB, периодически возвращайтесь сюда, чтобы ознакомиться с обновлениями. ## Чего следует избегать - Жаргона и сленга. - Использования «мы». - Шуток и другого эмоционального контента. - Чрезмерно длинных предложений. - Нерелевантных тем и отсылок, таких как культура, религия или политика. - Излишне подробных деталей реализации (кроме [Разработка YDB](https://ydb.tech/docs/ru/contributor/index.md?version=v25.3), [Список изменений YDB Server](https://ydb.tech/docs/ru/changelog-server.md?version=v25.3) и [Видеозаписи](https://ydb.tech/docs/ru/public-materials/videos.md?version=v25.3)). - Повторного использования стороннего контента без письменного разрешения или совместимой открытой лицензии, явно разрешающей это. - HTML внутри Markdown, кроме как для обхода отсутствующих визуальных стилей. ## См. также - [Участие в разработке документации YDB](https://ydb.tech/docs/ru/contributor/documentation/index.md?version=v25.3) - [Процесс ревью документации YDB](https://ydb.tech/docs/ru/contributor/documentation/review.md?version=v25.3) - [Структура документации YDB](https://ydb.tech/docs/ru/contributor/documentation/structure.md?version=v25.3) - [Жанры документации YDB](https://ydb.tech/docs/ru/contributor/documentation/genres.md?version=v25.3)