Move recommendation up in bootstrapping doc

Author: DaveCTurner

docs/reference/modules/discovery/bootstrapping.asciidoc

@@ -2,11 +2,11 @@
 === Bootstrapping a cluster
 
 Starting an Elasticsearch cluster for the very first time requires the initial
-set of <<master-node,master-eligible nodes>> to be explicitly defined on one or more of the
-master-eligible nodes in the cluster. This is known as _cluster bootstrapping_.
-This is only required the very first time the cluster starts up: nodes that
-have already joined a cluster store this information in their data folder
-and freshly-started nodes that are joining an existing cluster
+set of <<master-node,master-eligible nodes>> to be explicitly defined on one or
+more of the master-eligible nodes in the cluster. This is known as _cluster
+bootstrapping_.  This is only required the very first time the cluster starts
+up: nodes that have already joined a cluster store this information in their
+data folder and freshly-started nodes that are joining an existing cluster
 obtain this information from the cluster's elected master. This information is
 given using this setting:
 
@@ -17,15 +17,29 @@ given using this setting:
     this list is empty, meaning that this node expects to join a cluster that
     has already been bootstrapped.
 
-This setting can be given on the command line when starting up each
-master-eligible node, or added to the `elasticsearch.yml` configuration file on
-those nodes. Once the cluster has formed this setting is no longer required and
-is ignored. It need not be set on master-ineligible nodes, nor on
-master-eligible nodes that are started to join an existing cluster. Note that
-master-eligible nodes should use storage that persists across restarts. If they
-do not, and `cluster.initial_master_nodes` is set, and a full cluster restart
-occurs, then another brand-new cluster will form and this may result in data
-loss.
+This setting can be given on the command line or in the `elasticsearch.yml`
+configuration file when starting up a master-eligible node. Once the cluster
+has formed this setting is no longer required and is ignored. It need not be set
+on master-ineligible nodes, nor on master-eligible nodes that are started to
+join an existing cluster. Note that master-eligible nodes should use storage
+that persists across restarts. If they do not, and
+`cluster.initial_master_nodes` is set, and a full cluster restart occurs, then
+another brand-new cluster will form and this may result in data loss.
+
+It is technically sufficient to set `cluster.initial_master_nodes` on a single
+master-eligible node in the cluster, and only to mention that single node in the
+setting's value, but this provides no fault tolerance before the cluster has
+fully formed. It is therefore better to bootstrap using at least three
+master-eligible nodes, each with a `cluster.initial_master_nodes` setting
+containing all three nodes.
+
+NOTE: In alpha releases, all listed master-eligible nodes are required to be
+discovered before bootstrapping can take place. This requirement will be relaxed
+in production-ready releases.
+
+WARNING: You must set `cluster.initial_master_nodes` to the same list of nodes
+on each node on which it is set in order to be sure that only a single cluster
+forms during bootstrapping and therefore to avoid the risk of data loss.
 
 For a cluster with 3 master-eligible nodes (with <<node.name,node names>>
 `master-a`, `master-b` and `master-c`) the configuration will look as follows:
@@ -40,8 +54,8 @@ cluster.initial_master_nodes:
 
 Alternatively the IP addresses or hostnames (<<node.name,if node name defaults
 to the host name>>) can be used. If there is more than one Elasticsearch node
-with the same IP address or hostname then the transport ports must also be
-given to specify exactly which node is meant:
+with the same IP address or hostname then the transport ports must also be given
+to specify exactly which node is meant:
 
 [source,yaml]
 --------------------------------------------------
@@ -52,58 +66,39 @@ cluster.initial_master_nodes:
   - master-node-hostname
 --------------------------------------------------
 
-Like all node settings, it is also possible to specify the initial set of
-master nodes on the command-line that is used to start Elasticsearch:
+Like all node settings, it is also possible to specify the initial set of master
+nodes on the command-line that is used to start Elasticsearch:
 
 [source,bash]
 --------------------------------------------------
 $ bin/elasticsearch -Ecluster.initial_master_nodes=master-a,master-b,master-c
 --------------------------------------------------
 
-It is technically sufficient to set this on a single master-eligible node in
-the cluster, and only to mention that single node in the setting, but this
-provides no fault tolerance before the cluster has fully formed. It
-is therefore better to bootstrap using at least three master-eligible nodes.
-In any case, when specifying the list of initial master nodes, **it is vitally
-important** to configure each node with exactly the same list of nodes, to
-prevent two independent clusters from forming. Typically you will set this on
-the nodes that are mentioned in the list of initial master nodes.
-
-NOTE: In alpha releases, all listed master-eligible nodes are required to be
-  discovered before bootstrapping can take place. This requirement will be
-  relaxed in production-ready releases.
-
-WARNING: You must put exactly the same set of initial master nodes in each
-  configuration file (or leave the configuration empty) in order to be sure
-  that only a single cluster forms during bootstrapping and therefore to
-  avoid the risk of data loss.
-
 [float]
 ==== Choosing a cluster name
 
-The <<cluster.name,`cluster.name`>> setting enables you to create multiple clusters which are separated
-from each other. Nodes verify that they agree on their cluster name when they
-first connect to each other. If two nodes have different cluster names, 
-they will not communicate meaningfully and will not belong to the same cluster.
-The default value for the cluster name is `elasticsearch`, but it is
-recommended to change this to reflect the logical name of the cluster.
+The <<cluster.name,`cluster.name`>> setting enables you to create multiple
+clusters which are separated from each other. Nodes verify that they agree on
+their cluster name when they first connect to each other, and Elasticsearch
+will only form a cluster from nodes that all have the same cluster name. The
+default value for the cluster name is `elasticsearch`, but it is recommended to
+change this to reflect the logical name of the cluster.
 
 [float]
 ==== Auto-bootstrapping in development mode
 
 If the cluster is running with a completely default configuration then it will
-automatically bootstrap a cluster based on the nodes that could be discovered
-to be running on the same host within a short time after startup. This means
-that by default it is possible to start up several nodes on a single machine
-and have them automatically form a cluster which is very useful for development
+automatically bootstrap a cluster based on the nodes that could be discovered to
+be running on the same host within a short time after startup. This means that
+by default it is possible to start up several nodes on a single machine and have
+them automatically form a cluster which is very useful for development
 environments and experimentation.  However, since nodes may not always
 successfully discover each other quickly enough this automatic bootstrapping
 cannot be relied upon and cannot be used in production deployments.
 
-If any of the following settings are configured then auto-bootstrapping will
-not take place, and you must configure `cluster.initial_master_nodes` as
-described in the <<modules-discovery-bootstrap-cluster,section on cluster
-bootstrapping>>:
+If any of the following settings are configured then auto-bootstrapping will not
+take place, and you must configure `cluster.initial_master_nodes` as described
+in the <<modules-discovery-bootstrap-cluster,section on cluster bootstrapping>>:
 
 * `discovery.zen.hosts_provider`
 * `discovery.zen.ping.unicast.hosts`