docs: improve newly added materials

docs/cli.md

 # Описание параметров запуска
+Picodata является консольным приложением, которое поддерживает различные параметры запуска в виде аргументов командной строки. 
+
+Полный список аргументов доступен с помощью следующей команды:
 
 ```console
 $ picodata run --help
-picodata-run
-Run the Picodata instance
+```
+Ниже приводится описание этих аргументов.
 
-USAGE:
-    picodata run [OPTIONS]
+`-advertise <[host][:port]>`<br>
+Адрес, по которому другие инстансы смогут подключиться к данному инстансу. По умолчанию используется значение из аргумента `--listen`.
+Аналогичная переменная окружения: `PICODATA_ADVERTISE`.
 
-OPTIONS:
-        --advertise <[host][:port]>
-            Address the other instances should use to connect to this instance. Defaults to
-            `--listen` value [env: PICODATA_ADVERTISE=]
+`--cluster-id <name>`<br>
+Имя кластера. Инстанс не сможет стать частью кластера, если у него указано другое имя.
+Аналогичная переменная окружения: `PICODATA_CLUSTER_ID`.
 
-        --cluster-id <name>
-            Name of the cluster. The instance will refuse to join a cluster with a different name
-            [env: PICODATA_CLUSTER_ID=] [default: demo]
+`--data-dir <path>`<br>
+Директория, в которой инстанс будет сохранять свои данные для постоянного хранения.
+Аналогичная переменная окружения: `PICODATA_DATA_DIR`.
 
-        --data-dir <path>
-            Here the instance persists all of its data [env: PICODATA_DATA_DIR=] [default: .]
+`-e, --tarantool-exec <expr>`<br>
+Данный аргумент позволяет выполнить Lua-скрипт на Tarantool
 
-    -e, --tarantool-exec <expr>
-            Execute tarantool (Lua) script
+`--failure-domain <key=value>`<br>
+Список параметров географического расположения сервера (через запятую). Также этот аргумент называется _зоной доступности_.
+Каждый параметр должен быть в формате КЛЮЧ=ЗНАЧЕНИЕ.
+До тех пор пока не достигнуто максимальное количество репликасетов в кластере, Picodata
+будет избегать помещения двух инстансов в один репликасет если хотя бы один параметр зоны доступности у них совпадает.
+Соответственно, инстансы будут формировать новые репликасеты. Picodata следит за тем, чтобы репликасеты наполнялись
+инстансами с разными зонами доступности до тех пор пока не достигнут заданный фактор репликации.
+Аналогичная переменная окружения: `PICODATA_FAILURE_DOMAIN`.
 
-        --failure-domain <key=value>
-            Comma-separated list describing physical location of the server. Each domain is a key-
-            value pair. Until max replicaset count is reached, picodata will avoid putting two
-            instances into the same replicaset if at least one key of their failure domains has the
-            same value. Instead, new replicasets will be created. Replicasets will be populated with
-            instances from different failure domains until the desired replication factor is reached
-            [env: PICODATA_FAILURE_DOMAIN=]
+`-h, --help`<br>
+Вывод справочной информации
 
-    -h, --help
-            Print help information
+`--init-replication-factor <INIT_REPLICATION_FACTOR>`<br>
+Число реплик (инстансов с одинаковым набором хранимых данных) для каждого репликасета.
+Аргумент используется только при начальном создании кластера и в дальнейшем игнорируется. 
+Аналогичная переменная окружения: `PICODATA_INIT_REPLICATION_FACTOR`.
 
-        --init-replication-factor <INIT_REPLICATION_FACTOR>
-            Total number of replicas (copies of data) for each replicaset in the current group.
-            It's only accounted upon the group creation (adding the first instance in the group),
-            and ignored aftwerwards. [env: PICODATA_INIT_REPLICATION_FACTOR=] [default: 1]
+`--instance-id <name>`<br>
+Название инстанса. Если этот аргумент не указать, то название будет сгенерировано автоматически.
+Аналогичная переменная окружения: `PICODATA_INSTANCE_ID`.
 
-        --instance-id <name>
-            Name of the instance Empty value means that instance_id of a Follower will be generated
-            on the Leader [env: PICODATA_INSTANCE_ID=] [default: ]
+`-l, --listen <[host][:port]>`<br>
+Адрес и порт привязки инстанса. По умолчанию используется localhost:3301
+Аналогичная переменная окружения: `PICODATA_LISTEN`.
 
-    -l, --listen <[host][:port]>
-            Socket bind address [env: PICODATA_LISTEN=] [default: localhost:3301]
+`--log-level <LOG_LEVEL>`<br>
+Уровень регистрации событий. Возможные значения:  fatal, system, error, crit, warn, info, verbose, debug.
+По умолчанию используется уровень info.
+Аналогичная переменная окружения: `PICODATA_LOG_LEVEL`.
 
-        --log-level <LOG_LEVEL>
-            Log level [env: PICODATA_LOG_LEVEL=] [default: info] [possible values: fatal, system,
-            error, crit, warn, info, verbose, debug]
+`--peer <[host][:port]>`<br>
+Адрес другого инстанса. В данному аргументе можно передавать несколько значение через запятую.
+По умолчанию используеься значение localhost:3301, т.е. без связывания с каким-либо другим инстансом.
+Указание порта опционально. Аналогичная переменная окружения: `PICODATA_PEER`.
 
-        --peer <[host][:port]>
-            Address(es) of other instance(s) [env: PICODATA_PEER=] [default: localhost:3301]
+`--replicaset-id <name>`<br>
+Название целевого репликасета. Аналогичная переменная окружения: `PICODATA_REPLICASET_ID`
 
-        --replicaset-id <name>
-            Name of the replicaset [env: PICODATA_REPLICASET_ID=]
-```
+
+Подробнее об устройстве кластера и репликасетов Picodata см. разделе [Топология кластера Picodata](../deploy)

docs/deploy.md

@@ -24,7 +24,7 @@ picodata run --data-dir i3 --listen :3303
 
 ## Кластер на нескольких серверах
 
-Выше был показан запуск Picodata на одном сервере, что удобно для тестирования и отладки, но не отражает сценариев полноценного использования кластера. Поэтому пора запустить Picodata на нескольких серверах. Предположим, что их два: `192.168.0.1` и `192.168.0.2`. Порядок запуска будет следующим:
+Выше был показан запуск Picodata на одном сервере, что удобно для тестирования и отладки, но не отражает сценариев полноценного использования кластера. Поэтому ниже будет показан запуск Picodata на нескольких серверах. Предположим, что их два: `192.168.0.1` и `192.168.0.2`. Порядок действий будет следующим:
 
 На `192.168.0.1`:
 ```shell
@@ -42,7 +42,7 @@ picodata run --listen 192.168.0.2:3301 --peer 192.168.0.1:3301
 
 Значение параметра `--listen` не хранится в кластерной конфигурации и может меняться при перезапуске инстанса.
 
-Во-вторых, надо дать инстансам возможность обнаружить друг друга для того чтобы механизм [discovery](discovery.md) правильно собрал все найденные экземпляры Picodata в один кластер. Для этого в параметре `--peer` нужно указать адрес какого-либо соседнего инстанса. По умолчанию значение параметра `--peer` установлено в `127.0.0.1:3301`. Параметр `--peer` не влияет больше ни на что, кроме механизма обнаружения других инстансов.
+Во-вторых, надо дать инстансам возможность обнаружить друг друга для того чтобы механизм discovery правильно собрал все найденные экземпляры Picodata в один кластер. Для этого в параметре `--peer` нужно указать адрес какого-либо соседнего инстанса. По умолчанию значение параметра `--peer` установлено в `127.0.0.1:3301`. Параметр `--peer` не влияет больше ни на что, кроме механизма обнаружения других инстансов.
 
 Параметр `--advertise` используется для установки публичного IP-адреса и порта инстанса. Параметр сообщает, по какому адресу остальные инстансы должны обращаться к текущему. По умолчанию он равен `--listen`, поэтому в примере выше не упоминается. Но, например, в случае `--listen 0.0.0.0` его придется указать явно:
 
@@ -52,7 +52,7 @@ picodata run --listen 0.0.0.0:3301 --advertise 192.168.0.1:3301
 
 Значение параметра `--advertise` анонсируется кластеру при запуске инстанса. Его можно поменять при перезапуске инстанса или в процессе его работы командой `picodata set-advertise`.
 
-## Питомцы против стада
+## Именование инстансов
 
 Чтобы проще было отличать инстансы друг от друга, им можно давать имена:
 
@@ -96,11 +96,11 @@ picodata run --no-role
 
 Количество инстансов в репликасете определяется значением переменной `replication_factor`. Внутри <!-- группы инстансов --> кластера используется один и тот же `replication_factor`.
 
-Для ее инициализации служит параметр `--init-replication-factor`. Этот параметр играет роль только в момент <!-- создания группы (добавления первого инстанса) --> добавления первого инстанса. В этот момент значение из аргументов командной строки записывается в конфигурацию кластера. В дальнейшем значение параметра `--init-replication-factor` игнорируется.
+Управление количеством происходит через параметр `--init-replication-factor`, который используется только в момент <!-- создания группы (добавления первого инстанса) --> запуска первого инстанса. При этом, значение из аргументов командной строки записывается в конфигурацию кластера. В дальнейшем значение параметра `--init-replication-factor` игнорируется.
 
 <!-- Отредактировать фактор репликации, сохраненный в конфигурации кластера, можно командой `picodata set-replication-factor`. Редактирование конфигурации сказывается только на вновь добавляемых инстансах, но не затрагивает уже работающие. -->
 
-По мере усложнения топологии возникает еще один вопрос — как не допустить объединения в репликасет инстансов из одного и того же датацентра. Для этого введен параметр `--failure-domain` — _зона доступности_, отражающая признак физического размещения сервера, на котором выполняется инстанс Picodata. Это может быть как датацентр, так и какое-либо другое обозначение расположения: регион (например, `eu-east`), стойка, сервер, или собственное обозначение (blue, green, yellow). Ниже показан пример запуска инстанса Picodata с указанием зоны доступности:
+По мере усложнения топологии возникает еще один вопрос — как не допустить объединения в репликасет инстансов из одного и того же датацентра. Для этого в Picodata имеется параметр `--failure-domain` — _зона доступности_, отражающая признак физического размещения сервера, на котором выполняется инстанс Picodata. Это может быть как датацентр, так и какое-либо другое обозначение расположения: регион (например, `eu-east`), стойка, сервер, или собственное обозначение (blue, green, yellow). Ниже показан пример запуска инстанса Picodata с указанием зоны доступности:
 
 ```
 picodata run --init-replication-factor 2 --failure-domain region=us,zone=us-west-1
@@ -177,12 +177,13 @@ picodata run --cfg router.toml --listen :3302
 
 ## Динамическое переключение голосующих узлов в Raft (Raft voter failover)
 
-Все узлы Raft в кластере делятся на два типа: голосующие (`voter`) и неголосующие (`learner`). За консистентность Raft-группы отвечают только узлы первого типа. Для коммита каждой транзакции требуется собрать кворум из `N/2 + 1` из голосующих узлов. Неголосующие узлы в кворуме не участвуют.
+Все узлы Raft в кластере делятся на два типа: голосующие (`voter`) и неголосующие (`learner`). За консистентность Raft-группы отвечают только узлы первого типа. Для коммита каждой транзакции требуется собрать кворум из `N/2 + 1` голосующих узлов. Неголосующие узлы в кворуме не участвуют.
 
-Чтобы сохранить баланс между надежностью кластера и удобством его эксплуатации, в Picodata предусмотрена удобная функция — динамическое переключение типа узлов. Если один из голосующих узлов становится недоступен или прекращает работу (что может нарушить кворум в Raft), то тип `voter` автоматически присваивается одному из доступных неголосующих узлов. Переключение происходит незаметно для пользователя.
+Чтобы сохранить баланс между надежностью кластера и удобством его эксплуатации, в Picodata предусмотрена удобная функция — динамическое переключение типа узлов. Если один из голосующих узлов становится недоступным или прекращает работу (что может нарушить кворум в Raft), то тип `voter` автоматически присваивается одному из доступных неголосующих узлов. Переключение происходит незаметно для пользователя.
 
 Количество голосующих узлов в кластере не настраивается и зависит только от общего количества инстансов. Если инстансов 1 или 2, то голосующий узел один. Если инстансов 3 или 4, то таких узлов три. Для кластеров с 5 или более инстансами — пять голосующих узлов.
 
+Подробнее о запуске Picodata в командной строке см. разделе [Описание параметров запуска](../cli)
 <!--
 ## Configuration reference