ydb-platform · orange13 · Nov 18, 2025 · Nov 15, 2025 · Nov 17, 2025
@@ -0,0 +1,48 @@
+# [Название действия]
+
+[Краткое описание назначения команды. Если команда связана с другими, добавьте ссылки.]
+
+[{% note info/warning %}
+
+[Примечание, если необходимо]
+
+{% endnote %}]
+
+Общий вид команды:
+
+    {{ ydb-cli }} [global options...] <command> [options...] [arguments...]
+
+* `global options` — [глобальные параметры](commands/global-options.md).
+* `options` — [параметры подкоманды](#options).
+* `arguments` — [описание аргументов].
+
+Посмотрите описание команды:
+
+    {{ ydb-cli }} <command> --help
+
+## Параметры подкоманды {#options}
+
+[Если команда имеет параметры, добавьте таблицу или описание]
+
+Имя | Описание
+|---|---
+`--parameter VAL` | Описание параметра.
+
+## Примеры {#examples}
+
+{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
+
+[Пример 1]:
+
+    {{ ydb-cli }} -p quickstart <command> [options...]
+
+[Пример 2 с результатом]:
+
+    {{ ydb-cli }} -p quickstart <command> [options...]
+
+Результат:
+
+    [Вывод команды]
+
+[Ссылки на связанные команды или статьи, если необходимо]
+
@@ -0,0 +1,321 @@
+# Документирование новых команд CLI
+
+Эта статья описывает процесс создания документации для новых команд {{ ydb-short-name }} CLI. Она содержит шаблон и рекомендации, основанные на существующих статьях о командах CLI.
+
+## Общие принципы
+
+Перед началом работы над документацией новой команды:
+
+1. Ознакомьтесь с [{#T}](style-guide.md) для понимания общих правил стиля документации.
+2. Убедитесь, что команда реализована и доступна в CLI с опцией `--help`.
+
+## Структура статьи
+
+Каждая статья о команде CLI должна следовать следующей структуре:
+
+### 1. Заголовок первого уровня
+
+Заголовок должен кратко описывать действие команды. Используйте формулировку, которая начинается с существительного или отглагольного существительного.
+
+**Примеры:**
+
+- `# Создание топика`
+- `# Удаление таблицы`
+- `# Получение статуса фоновой операции`
+- `# Чтение из топика`
+
+### 2. Краткое описание
+
+Первые 1–3 предложения описывают назначение команды. Если команда связана с другими командами, добавьте ссылки на них.
+
+**Пример:**
+
+```markdown
+С помощью подкоманды `topic create` вы можете создать новый топик.
+```
+
+**Пример со ссылкой:**
+
+```markdown
+С помощью команды `topic consumer add` вы можете добавить читателя для [созданного ранее](topic-create.md) топика.
+```
+
+### 3. Примечания (опционально)
+
+Если команда имеет важные особенности, ограничения или предупреждения, добавьте их сразу после описания с помощью блока `{% note %}`.
+
+**Пример:**
+
+```markdown
+{% note info %}
+
+При удалении топика также будут удалены все добавленные для него читатели.
+
+{% endnote %}
+```
+
+### 4. Общий вид команды
+
+Покажите синтаксис команды с использованием шаблона `{{ ydb-cli }}` и правильного форматирования.
+
+**Базовый шаблон:**
+
+```markdown
+Общий вид команды:
+
+{{ ydb-cli }} [global options...] <command> [options...] [arguments...]
+
+* `global options` — [глобальные параметры](commands/global-options.md).
+* `options` — [параметры подкоманды](#options).
+* `arguments` — аргументы команды (опишите каждый).
+```
+
+**Примеры:**
+
+Для команды без опций:
+
+```markdown
+{{ ydb-cli }} [global options...] topic drop <topic-path>
+```
+
+Для команды с опциями:
+
+```markdown
+{{ ydb-cli }} [global options...] topic create [options...] <topic-path>
+```
+
+Для сложной команды:
+
+```markdown
+{{ ydb-cli }} [connection options] topic read <topic-path> [--consumer STR] \
+  [--format STR] [--wait] [--limit INT] \
+  [--transform STR] [--file STR] [--commit BOOL] \
+  [дополнительные параметры...]
+```
+
+### 5. Ссылка на справку
+
+Всегда добавляйте команду для получения справки:
+
+```markdown
+Посмотрите описание команды:
+
+{{ ydb-cli }} <command> --help
+```
+
+### 6. Параметры подкоманды
+
+Если команда имеет параметры, создайте раздел `## Параметры подкоманды {#options}`.
+
+Оформите параметры в виде таблицы:
+
+```markdown
+## Параметры подкоманды {#options}
+
+Имя | Описание
+|---|---
+`--parameter-name VAL` | Описание параметра.
+```
+
+**Рекомендации по описанию параметров:**
+
+- Укажите тип значения, если он важен (например, `VAL`, `STR`, `INT`, `BOOL`).
+- Укажите значение по умолчанию, если оно есть.
+- Перечислите возможные значения для перечислений.
+- Добавьте ссылки на концепции, если параметр связан с ними.
+- Используйте HTML-теги для форматирования внутри ячеек таблицы (например, `<br/>`, `<ul>`, `<li>`).
+
+**Пример простого параметра:**
+
+```markdown
+`--consumer VAL` | Имя читателя, которого нужно добавить.
+```
+
+**Пример параметра с описанием:**
+
+```markdown
+`--retention-period` | Время хранения данных в топике. Положительное число с указанием единицы измерения.<br/>Поддерживаются следующие единицы:<ul><li>`s` – секунды;</li><li>`m` – минуты;</li><li>`h` – часы;</li><li>`d` – дни.</li></ul>Значение по умолчанию — `18h`.
+```
+
+**Пример параметра со ссылкой:**
+
+```markdown
+`--partitions-count`| Количество [партиций](../../concepts/datamodel/topic.md#partitioning) топика.<br/>Значение по умолчанию — `1`.
+```
+
+**Группировка параметров:**
+
+Для команд с большим количеством параметров можно разделить их на группы:
+
+```markdown
+## Параметры {#options}
+
+### Обязательные параметры
+
+`<topic-path>`: Путь топика
+
+### Основные опциональные параметры
+
+`-c VAL`, `--consumer VAL`: Имя читателя топика.
+
+### Другие опциональные параметры
+
+| Имя | Описание |
+|-----|----------|
+| `--idle-timeout VAL` | Таймаут принятия решения о том что топик пуст. |
+```
+
+### 7. Примеры
+
+Всегда добавляйте раздел с примерами использования команды.
+
+**Шаблон раздела примеров:**
+
+```markdown
+## Примеры {#examples}
+
+{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
+
+[Описание примера]:
+```
+
+**Рекомендации по примерам:**
+
+- Начинайте каждый пример с краткого описания того, что он демонстрирует.
+- Используйте профиль `quickstart` для примеров: `{{ ydb-cli }} -p quickstart ...`
+- Показывайте результаты выполнения команды, если они важны для понимания.
+- Группируйте связанные примеры.
+- Добавляйте ссылки на связанные команды или статьи в конце раздела, если это уместно.
+
+**Пример простого использования:**
+
+```markdown
+Создайте читателя с именем `my-consumer` для [созданного ранее](topic-create.md) топика `my-topic`:
+
+{{ ydb-cli }} -p quickstart topic consumer add \
+  --consumer my-consumer \
+  my-topic
+```
+
+**Пример с результатом:**
+
+```markdown
+Убедитесь, что читатель создан:
+
+{{ ydb-cli }} -p quickstart scheme describe my-topic
+
+Результат:
+
+    RetentionPeriod: 2 hours
+    PartitionsCount: 2
+    SupportedCodecs: RAW, GZIP
+
+    Consumers:
+    ┌──────────────┬─────────────────┬───────────────────────────────┬───────────┐
+    || ConsumerName | SupportedCodecs | ReadFrom                      | Important |
+    ├──────────────┼─────────────────┼───────────────────────────────┼───────────┤
+    || my-consumer  | RAW, GZIP       | Mon, 15 Aug 2022 16:00:00 MSK | 0         |
+    └──────────────┴─────────────────┴───────────────────────────────┴───────────┘
+```
+
+**Пример с несколькими вариантами использования:**
+
+```markdown
+* Чтение одного сообщения с выводом в терминал:
+
+{{ ydb-cli }} -p quickstart topic read topic1 -c c1
+
+* Ожидание появления и чтение одного сообщения с записью его в файл:
+
+{{ ydb-cli }} -p quickstart topic read topic1 -c c1 -w -f message.bin
+```
+
+## Полный шаблон статьи
+
+Полный шаблон статьи доступен в отдельном файле: [шаблон](https://github.com/ydb-platform/ydb/tree/main/ydb/docs/ru/core/contributor/documentation/_templates/cli-command-template.md). Используйте его как основу при создании документации для новой команды CLI.
+
+## Специальные случаи
+
+### Команды без параметров
+
+Если команда не имеет параметров (кроме глобальных), раздел "Параметры подкоманды" можно опустить.
+
+**Пример:**
+
+```markdown
+# Удаление топика
+
+С помощью подкоманды `topic drop` вы можете удалить [созданный ранее](topic-create.md) топик.
+
+Общий вид команды:
+
+{{ ydb-cli }} [global options...] topic drop <topic-path>
+
+* `global options` — [глобальные параметры](commands/global-options.md).
+* `topic-path` — путь топика.
+
+Посмотрите описание команды удаления топика:
+
+{{ ydb-cli }} topic drop --help
+
+## Примеры {#examples}
+...
+```
+
+### Команды с режимами работы
+
+Если команда поддерживает несколько режимов работы, опишите их перед разделом параметров.
+
+**Пример:**
+
+```markdown
+Поддерживается три режима работы команды:
+
+1. **Одно сообщение**. Из топика считывается не более одного сообщения.
+2. **Пакетный режим**. Сообщения из топика считываются до того момента, пока в топике не закончатся сообщения для обработки.
+3. **Потоковый режим**. Сообщения из топика считываются по мере их появления.
+```
+
+
+### Предупреждения об устаревших командах
+
+Если команда устарела, добавьте предупреждение в начале статьи:
+
+```markdown
+{% include notitle [warning](../../reference/ydb-cli/_includes/deprecated_command_warning.md) %}
+```
+
+## Именование файлов
+
+- Используйте дефисы вместо подчёркиваний: `topic-create.md`, а не `topic_create.md`.
+- Имя файла должно соответствовать структуре команды: `topic-consumer-add.md` для команды `topic consumer add`.
+- Для простых команд используйте короткие имена: `version.md`, `table-drop.md`.
+
+## Интеграция в документацию
+
+После создания статьи:
+
+1. **Добавьте ссылку в `_includes/commands.md`** — общий список всех команд CLI.
+2. **Обновите оглавление** — добавьте статью в соответствующий `toc_i.yaml` или `toc_p.yaml`.
+3. **Добавьте перекрёстные ссылки** — обновите связанные статьи, добавив ссылки на новую команду.
+4. **Проверьте ссылки** — убедитесь, что все внутренние ссылки корректны и используют относительные пути с суффиксом `.md`.
+
+## Проверка перед публикацией
+
+Перед отправкой pull request убедитесь, что:
+
+- [ ] Статья следует структуре, описанной выше.
+- [ ] Все примеры протестированы и работают корректно.
+- [ ] Используются правильные переменные: `{{ ydb-cli }}`, `{{ ydb-short-name }}`.
+- [ ] Все ссылки корректны и используют относительные пути с `.md`.
+- [ ] Статья добавлена в оглавление и список команд.
+- [ ] Текст соответствует [руководству по стилю](style-guide.md).
+- [ ] Нет опечаток и грамматических ошибок.
+
+## См. также
+
+- [{#T}](style-guide.md) — общее руководство по стилю документации
+- [{#T}](structure.md) — структура документации
+- [{#T}](review.md) — процесс ревью документации
+- [Примеры существующих статей](../../reference/ydb-cli/index.md) — изучите похожие команды для вдохновения
+
@@ -18,4 +18,5 @@
 - [{#T}](genres.md)
 - [Документация GitHub](https://docs.github.com/en)
 - [Документация Git](https://git-scm.com/doc)
-- [{#T}](guide-to-public-material.md)
+- [{#T}](guide-to-public-material.md)
+- [{#T}](cli-command-documentation.md)
@@ -8,4 +8,6 @@ items:
 - name: Жанры
   href: genres.md
 - name: Добавление медиа в публичные материалы
-  href: guide-to-public-material.md  
+  href: guide-to-public-material.md
+- name: Документирование новых команд CLI
+  href: cli-command-documentation.md