Supervised failover: update per TW review 1

Author: andreyaksenov

doc/book/admin/start_stop_instance.rst

@@ -26,7 +26,7 @@ To get more context on how the application's environment might look, refer to :r
 Starting Tarantool instances
 ----------------------------
 
-The :ref:`tt <tt-cli>` utility is the recommended way to start Tarantool instances.
+To start Tarantool instances use the :ref:`tt start <tt-start>` command:
 
 .. code-block:: console
 

doc/reference/tarantool_cli_options.rst

@@ -4,16 +4,22 @@
 tarantool command-line options
 ==============================
 
-This topic describes options that can be passed to the ``tarantool`` command.
-These options might be helpful for development purposes.
+``tarantool`` is the Tarantool database and application server.
+This command can be used for different purposes, for example, running a single Tarantool instance or starting an external coordinator used for a :ref:`supervised failover <repl_supervised_failover>`.
+The ``tarantool`` command also provides additional :ref:`options <tarantool_cli_options>` that might be helpful for development purposes.
+
+..  NOTE::
+
+    The :ref:`tt <tt-cli>` utility is the recommended way to start Tarantool instances.
+    Learn more from :ref:`admin-start_stop_instance`.
+
+
 
 .. _configuration_run_instance_tarantool:
 
 Starting instances using the tarantool command
 ----------------------------------------------
 
-The ``tarantool`` command provides additional :ref:`options <_tarantool_cli_options>` that might be helpful for development purposes.
-
 Below is the syntax for starting a Tarantool instance configured in a file:
 
 ..  code-block:: console
@@ -91,7 +97,7 @@ Options
     Set a path to a :ref:`YAML configuration file <configuration_file>`.
     You can also configure this value using the ``TT_CONFIG`` environment variable.
 
-    See also: :ref:`Starting an instance using the tarantool command <configuration_run_instance_tarantool>`
+    See also: :ref:`configuration_run_instance_tarantool`
 
 
 .. _tarantool_cli_name:
@@ -103,7 +109,7 @@ Options
     Set the name of an instance to run.
     You can also configure this value using the ``TT_INSTANCE_NAME`` environment variable.
 
-    See also: :ref:`Starting an instance using the tarantool command <configuration_run_instance_tarantool>`
+    See also: :ref:`configuration_run_instance_tarantool`
 
 .. _tarantool_cli_i:
 

doc/reference/tooling/tt_cli/cluster.rst

@@ -5,9 +5,9 @@ Managing cluster configurations
 
 .. code-block:: console
 
-    $ tt cluster COMMAND {APPLICATION[:APP_INSTANCE] | URI} [FILE] [OPTION ...]
+    $ tt cluster [OPTION ...] COMMAND [COMMAND_OPTION ...]
 
-``tt cluster`` manages :ref:`YAML configurations <configuration>` of Tarantool applications.
+``tt cluster`` manages :ref:`configurations <configuration>` of Tarantool applications.
 This command works both with local YAML files in application directories
 and with :ref:`centralized configuration storages <configuration_etcd>` (etcd or Tarantool-based).
 
@@ -25,7 +25,7 @@ publish
 
 .. code-block:: console
 
-    $ tt cluster publish {APPLICATION[:APP_INSTANCE] | URI} [FILE] [OPTION ...]
+    $ tt cluster publish {APPLICATION[:APP_INSTANCE] | CONFIG_URI} [FILE] [OPTION ...]
 
 ``tt cluster publish`` publishes a cluster configuration using an arbitrary YAML file as a source.
 
@@ -119,7 +119,7 @@ show
 
 .. code-block:: console
 
-    $ tt cluster show {APPLICATION[:APP_INSTANCE] | URI} [OPTION ...]
+    $ tt cluster show {APPLICATION[:APP_INSTANCE] | CONFIG_URI} [OPTION ...]
 
 ``tt cluster show`` displays a cluster configuration.
 
@@ -197,7 +197,7 @@ replicaset
 
 .. code-block:: console
 
-    $ tt cluster replicaset SUBCOMMAND {APPLICATION[:APP_INSTANCE] | URI} [OPTION ...]
+    $ tt cluster replicaset SUBCOMMAND {APPLICATION[:APP_INSTANCE] | CONFIG_URI} [OPTION ...]
 
 ``tt cluster replicaset`` manages instances in a replica set. It supports the following
 subcommands:
@@ -218,7 +218,7 @@ promote
 
 .. code-block:: console
 
-    $ tt cluster replicaset promote URI INSTANCE_NAME [OPTION ...]
+    $ tt cluster replicaset promote CONFIG_URI INSTANCE_NAME [OPTION ...]
 
 ``tt cluster replicaset promote`` promotes the specified instance,
 making it a leader of its replica set.
@@ -251,7 +251,7 @@ demote
 
 .. code-block:: console
 
-    $ tt cluster replicaset demote URI INSTANCE_NAME [OPTION ...]
+    $ tt cluster replicaset demote CONFIG_URI INSTANCE_NAME [OPTION ...]
 
 ``tt cluster replicaset demote`` demotes an instance in a replica set.
 This command works on Tarantool clusters with centralized configuration and
@@ -298,23 +298,26 @@ switch
 
 .. code-block:: console
 
-    $ tt cluster failover switch URI INSTANCE_NAME [OPTION ...]
+    $ tt cluster failover switch CONFIG_URI INSTANCE_NAME [OPTION ...]
 
 ``tt cluster failover switch`` appoints the specified instance to be a master.
 This command accepts the following arguments and options:
 
--   ``URI``: A :ref:`URI <tt-cluster-uri>` of the cluster configuration storage.
+-   ``CONFIG_URI``: A :ref:`URI <tt-cluster-uri>` of the cluster configuration storage.
 -   ``INSTANCE_NAME``: An instance name.
 -   ``[OPTION ...]``: :ref:`Options <tt-cluster-options>` to pass to the command.
 
-Example:
+In the example below, ``tt cluster failover switch`` appoints ``storage-a-002`` to be a master:
 
 .. code-block:: console
 
     $ tt cluster failover switch http://localhost:2379/myapp storage-a-002
     To check the switching status, run:
     tt cluster failover switch-status http://localhost:2379/myapp b1e938dd-2867-46ab-acc4-3232c2ef7ffe
 
+Note that the command output includes an identifier of the task responsible for switching a master.
+You can use this identifier to see the status of switching a master instance using ``tt cluster failover switch-status``.
+
 
 .. _tt-cluster-failover-switch-status:
 
@@ -323,13 +326,13 @@ switch-status
 
 .. code-block:: console
 
-    $ tt cluster failover switch-status URI TASK_ID
+    $ tt cluster failover switch-status CONFIG_URI TASK_ID
 
 ``tt cluster failover switch-status`` shows the status of switching a master instance.
 This command accepts the following arguments:
 
--   ``URI``: A :ref:`URI <tt-cluster-uri>` of the cluster configuration storage.
--   ``TASK_ID``: An identifier of the task used to switch a master instance.
+-   ``CONFIG_URI``: A :ref:`URI <tt-cluster-uri>` of the cluster configuration storage.
+-   ``TASK_ID``: An identifier of the task used to switch a master instance. You can find the task identifier in the ``tt cluster failover switch`` command output.
 
 Example:
 
@@ -447,7 +450,7 @@ Options
 
     Skip validation when publishing. Default: `false` (validation is enabled).
 
-..  option:: --t, --timeout UINT
+..  option:: -t, --timeout UINT
 
     **Applicable to:** ``failover``
 
@@ -474,4 +477,4 @@ Options
 
     **Applicable to:** ``publish``
 
-    Generate hashes and signatures for integrity checks.
+    Generate hashes and signatures for integrity checks.