ydb-platform · anton-bobkov · Mar 20, 2025 · Mar 20, 2025 · Mar 20, 2025 · Mar 20, 2025
@@ -1,6 +1,6 @@
 # Review process for {{ ydb-short-name }} documentation
 
-Building on the high-level overview in [{#T}](index.md), this article dives deeper into what happens during the pull request review stage.
+Building on the high-level overview in [{#T}](index.md), this article dives deeper into what happens during the documentation pull request review stage.
 
 ## Roles
 
@@ -48,7 +48,7 @@ Building on the high-level overview in [{#T}](index.md), this article dives deep
 - [ ] Each article follows a single [genre](genres.md) and aligns with its place in the documentation structure.
 - [ ] Each new article includes links to all relevant existing documentation pages, either inline or in a "See also" section.
 - [ ] Relevant existing articles are updated with links to new articles.
-- [ ] All new articles are listed in table of contents and their folder's `index.md`.
+- [ ] All new articles are listed in YAML files with table of contents and their folder's `index.md`.
 - [ ] All renamed or moved articles are reflected in [redirects.yaml](https://github.com/ydb-platform/ydb/blob/main/ydb/docs/redirects.yaml).
 - [ ] The article's voice, tone, and style match the rest of the documentation or, at a minimum, remain consistent within the article.
 

@@ -22,7 +22,7 @@ Introducing new top-level folders is possible, but it requires careful considera
 - **[For Developers](../../dev/index.md).** A folder for application developers working with {{ ydb-short-name }}. Primarily consists of [practical guides](genres.md#guide) and some [theory](genres.md#theory).
 - **[For Security Engineers](../../security/index.md).** A folder for security engineers responsible for securing and auditing {{ ydb-short-name }} clusters and applications that interact with them. Contains mostly [practical guides](genres.md#guide) and some role-specific [theory](genres.md#theory).
 - **[For Contributors](../../contributor/index.md)**.** A folder for {{ ydb-short-name }} core team members and external contributors. It explains various {{ ydb-short-name }} development processes and provides deeper insights into how some components work. Mostly [theory](genres.md#theory) with some [practical guides](genres.md#guide).
-- **[Reference](../../reference/index.md).** A detailed [reference](genres.md#reference) section covering various aspects of {{ ydb-short-name }}, designed to be found as needed. The primary goal is completeness so that any topic can be located through exact keyword matches or descriptions. The three main use cases for this section are:
+- **[Reference](../../reference/index.md).** A detailed [reference](genres.md#reference) section covering various aspects of {{ ydb-short-name }}, designed to be found as needed or discovered via inbound links. The primary goal is completeness so that any topic can be located through exact keyword matches or descriptions. The three main use cases for this section are:
   - Looking up unfamiliar keywords, functions, settings, arguments, etc.
   - Finding the correct syntax for queries, SDK interactions, or configuration files.
   - Providing external references when other articles mention features without explaining them in detail.

@@ -56,9 +56,9 @@ Ensure that text follows proper language rules with no typos, grammar, punctuati
 - **Code and samples.** When including code, use proper syntax highlighting, formatting, and comments to ensure readability. Show example output for queries and CLI commands. Use `code blocks` for everything likely to appear in a console or IDE, but not for visual highlights.
 - **Linking and references.** Provide clear and descriptive links to related resources or additional documentation. Instead of repeating the target's header for internal links, use `[{#T}](path/to/an/article.md)`.
 - **No copy-pasting.** If a piece of information needs to be displayed more than once, create a separate Markdown file in the `_includes` folder, then add it to all necessary places via `{% include [...](_includes/path/to/a/file.md) %}` instead of duplicating content by copying and pasting.
-- **Markdown syntax style.** {{ ydb-short-name }} uses an automated linter for Markdown files. Refer to [.yfmlint](https://github.com/ydb-platform/ydb/blob/main/ydb/docs/.yfmlint) for the up-to-date list of enforced rules.
+- **Markdown syntax style.** {{ ydb-short-name }} documentation uses an automated linter for Markdown files. Refer to [.yfmlint](https://github.com/ydb-platform/ydb/blob/main/ydb/docs/.yfmlint) for the up-to-date list of enforced rules.
 - **Variable usage.** The {{ ydb-short-name }} documentation has a configuration file, [presets.yaml](https://github.com/ydb-platform/ydb/blob/main/ydb/docs/presets.yaml), that lists variables to prevent typos or conditionally hide content. Use these variables when appropriate, particularly `{{ ydb-short-name }}` instead of `YDB`.
-- **Diagrams.** Prefer built-in [Mermaid](https://github.com/diplodoc-platform/mermaid-extension) diagrams when possible. If using an external tool, submit the source file in the same folder for future edits. Ensure diagrams look good in both light and dark modes.
+- **Diagrams.** Prefer built-in [Mermaid](https://github.com/diplodoc-platform/mermaid-extension) diagrams when possible. If using an external tool, submit the source file in the same `_assets` folder near image for future edits. Ensure diagrams look good in both light and dark modes.
 - **Proper article placement.** New articles should be correctly placed in the [documentation structure](structure.md).
 - **Genre consistency.** Articles should not mix multiple [genres](genres.md), and the genre should match the article's place in the documentation structure.
 

@@ -0,0 +1,102 @@
+## Жанры документации {{ ydb-short-name }}
+
+Эта статья дополняет [{#T}](style-guide.md), описывая основные жанры статей, используемые в документации {{ ydb-short-name }}. Понимание этих жанров помогает контрибьюторам размещать новый контент в соответствующем разделе и поддерживать консистентную структуру материалов.
+
+### Теория {#theory}
+
+**Основная цель для читателя:** построить прочный фундамент знаний и прийти к пониманию основных концепций, архитектуры и принципов, на которых работает {{ ydb-short-name }}.
+
+Теоретическая документация:
+
+- вводит ключевые концепции и терминологию;
+- объясняет, как система работает как с точки зрения пользователя, так и изнутри;
+- предоставляет высокоуровневые обзоры компонентов системы;
+- помогает пользователям понять «почему» за архитектурными решениями;
+- может быть нацелен либо на широкую аудиторию с минимальными предварительными знаниями, либо на конкретную роль;
+- может включать диаграммы и другие визуализации для помощи в передаче информации.
+
+Теоретическая документация в основном находится в разделе [{#T}](../../concepts/index.md), но также появляется и в папках, специфичных для ролей, когда теоретическая информация релевантна только для конкретной аудитории.
+
+### Руководство {#guide}
+
+**Основная цель для читателя:** выполнить конкретную практическую задачу или реализовать определённое решение с помощью {{ ydb-short-name }}, следуя инструкциям.
+
+Руководства — это практические пошаговые инструкции, которые помогают пользователям достичь конкретной цели с помощью {{ ydb-short-name }}. Каждая статья в этом жанре:
+
+- предоставляет чёткую цель и последовательные инструкции для её достижения;
+- включает конкретные примеры и команды;
+- фокусируется на практической реализации;
+- освещает конкретные сценарии использования;
+- может включать скриншоты для иллюстрации шагов.
+
+Руководства в основном находятся в папках, специфичных для ролей, таких как [{#T}](../../devops/index.md), [{#T}](../../dev/index.md) и [{#T}](../../security/index.md), а также в разделе [{#T}](../../troubleshooting/index.md).
+
+### Справочник {#reference}
+
+**Основная цель для читателя:** найти дополнительную информацию по конкретной узкой теме, связанной с {{ ydb-short-name }}.
+
+Справочная документация предоставляет всестороннюю, подробную информацию о компонентах {{ ydb-short-name }}, запросах, API, параметрах конфигурации, CLI-командах, страницах UI и многом другом. Этот жанр:
+
+- стремится к полноте и точности;
+- служит ресурсом для поиска конкретных деталей;
+- документирует все доступные опции, параметры и настройки;
+- организован для быстрого поиска информации через поисковую систему или [LLM](https://ru.wikipedia.org/wiki/Большая_языковая_модель);
+- включает синтаксис, типы данных, параметры, возвращаемые значения, значения по умолчанию, конфигурацию и примеры.
+
+Справочная документация разработана для поиска по мере необходимости и является самым подробным уровнем документации. Она особенно полезна, когда пользователям нужна конкретная информация о функциях, настройках или ключевых словах. Этот контент в основном находится в разделе [{#T}](../../reference/index.md).
+
+### FAQ {#faq}
+
+**Основная цель для читателя:** быстро найти ответы на распространённые вопросы, возникающие при работе с {{ ydb-short-name }}.
+
+Документация часто задаваемых вопросов (FAQ) отвечает на общие вопросы о {{ ydb-short-name }} в формате прямых вопросов и ответов на них. Этот жанр:
+
+- обращается к конкретным, часто задаваемым вопросам;
+- предоставляет краткие, сфокусированные ответы;
+- организован по темам или категориям;
+- помогает пользователям быстро находить решения типовых проблем;
+- оптимизирован для обнаружения поисковыми системами или LLM.
+
+Контент FAQ в основном находится в разделе [{#T}](../../faq/index.md) и разработан для помощи пользователям, которые ищут конкретные решения для типовых ситуаций.
+
+### Рецепт {#recipe}
+
+**Основная цель для читателя:** реализовать конкретное, сфокусированное решение для типовой проблемы или сценария использования с помощью {{ ydb-short-name }}.
+
+Рецепты — это короткие, сфокусированные мини-руководства, которые демонстрируют, как выполнять конкретные задачи с помощью {{ ydb-short-name }}. Этот жанр:
+
+- предоставляет краткие решения для конкретных проблем;
+- включает фрагменты кода и примеры;
+- акцентирует внимание на практической реализации;
+- более узко сфокусирован, чем полноценные [руководства](#guide);
+- часто следует формату проблема-решение.
+
+Рецепты в основном находятся в разделе [{#T}](../../recipes/index.md), хотя похожий контент может также появляться в папках, специфичных для роли.
+
+### Заметки о выпуске {#release-notes}
+
+**Основная цель для читателя:** быть в курсе новых функций, улучшений, исправлений ошибок и критических изменений в выпусках {{ ydb-short-name }}.
+
+Заметки о выпуске документируют изменения, улучшения и исправления в каждой новой версии {{ ydb-short-name }}. Этот жанр:
+
+- перечисляет новые функции и улучшения;
+- документирует исправления ошибок и решённые проблемы;
+- выделяет критические изменения и устаревшие функции;
+- предоставляет инструкции по обновлению при необходимости;
+- организован хронологически по номеру версии.
+
+Заметки о выпуске находятся в разделе [{#T}](../../changelog-server.md) и помогают пользователям понять, что изменилось между версиями, и решить, обновляться ли.
+
+### Коллекция ссылок {#links}
+
+**Основная цель для читателя:** открыть для себя дополнительные ресурсы, учебные материалы и внешний контент, связанный с {{ ydb-short-name }}.
+
+Коллекции ссылок предоставляют курированные списки ресурсов, связанных с {{ ydb-short-name }}. Этот жанр:
+
+- агрегирует релевантные сторонние или внутренние ресурсы;
+- предоставляет краткие описания каждого связанного ресурса;
+- может быть организован по темам, форматам или степени релевантности;
+- помогает пользователям открывать для себя дополнительные учебные материалы;
+- может включать видео, статьи, загрузки и другой контент.
+
+Коллекции ссылок в основном находятся в разделах [{#T}](../../public-materials/videos.md) и [{#T}](../../downloads/index.md) и выступают входными точками к внешним ресурсам о {{ ydb-short-name }}.