Edit actions for consistency and add action template. (#55632)

* Edit actions for consistency and add action template.

* Update docs/reference/ilm/actions/ilm-readonly.asciidoc

Co-Authored-By: James Rodewig <james.rodewig@elastic.co>

* Apply suggestions from code review

docs/reference/ilm/actions/_ilm-action-template.asciidoc

@@ -0,0 +1,94 @@
+////
+This is a template for ILM action reference documentation.
+
+To document a new action, copy this file, remove comments like this, and
+replace "sample" with the appropriate action name.
+
+Ensure the new action docs are linked and included in
+docs/reference/ilm/actions.asciidoc
+////
+
+[role="xpack"]
+[[ilm-sample]]
+=== Sample
+
+Phases allowed: hot, warm, cold, delete.
+
+////
+INTRO
+Include a brief, 1-2 sentence description.
+////
+
+Does a cool thing. 
+
+[[ilm-sample-options]]
+==== Options
+
+////
+Definition list of the options that can be specified for the action:
+
+If there are no options:
+
+None.
+////
+
+`sample_option1`::
+(Optional, integer)
+Number of something.
+
+`sample_option2`::
+(Required, string)
+Name of something.
+
+[[ilm-sample-ex]]
+==== Example
+
+////
+Basic example of configuring the action in an ILM policy.
+
+Additional examples are optional.
+////
+
+[source,console]
+--------------------------------------------------
+PUT _ilm/policy/my_policy
+{
+  "policy": {
+    "phases": {
+      "warm": {
+        "actions": {
+          "sample" : {
+            "sample_option1" : 2
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TEST[skip: Replace fake actions and remove this comment.]
+
+[[ilm-sample2-ex]]
+===== Describe example
+
+The sample action in the following policy does something interesting. 
+
+[source,console]
+--------------------------------------------------
+PUT _ilm/policy/my_policy
+{
+  "policy": {
+    "phases": {
+      "warm": {
+        "actions": {
+          "sample" : {
+            "sample_option1" : 100,
+            "sample_option2" : "interesting"
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TEST[skip: Replace fake actions and remove this comment.]

docs/reference/ilm/actions/ilm-allocate.asciidoc

@@ -4,27 +4,24 @@
 
 Phases allowed: warm, cold.
 
-Specifies which nodes are allowed to host the
-shards of an index and set the number of replicas.
+Updates the index settings to change which nodes are allowed to host the index shards
+and change the number of replicas.
 
-Behind the scenes, the allocate action modifies the index settings
-for shard filtering and/or replica counts. When updating the number of replicas,
-configuring allocation rules is optional. When configuring allocation rules,
-setting number of replicas is optional. Although this action can be treated as
-two separate index settings updates, both can be configured at once.
+You can configure this action to modify both the allocation rules and number of replicas, 
+only the allocation rules, or only the number of replicas. 
 
 For more information about how {es} uses replicas for scaling, see
 <<scalability>>. See <<shard-allocation-filtering>> for more information about
 controlling where {es} allocates shards of a particular index.
 
-NOTE: The allocate action is not allowed in the hot phase, 
-so the initial allocation for the index should be done manually or via index templates.
-{ilm-init} won't take care of index allocation during the `hot` phase.
+NOTE: The allocate action is not allowed in the hot phase. 
+The initial allocation for the index must be done manually or via index templates.
+{ilm-init} doesn't handle index allocation during the hot phase.
 
 [[ilm-allocate-options]]
-==== Allocate options
+==== Options
 
-You must either specify the number of replicas or at least one 
+You must specify the number of replicas or at least one 
 `include`, `exclude`, or `require` option. 
 An empty allocate action is invalid.
 
@@ -47,14 +44,11 @@ Assigns an index to nodes that have _none_ of the specified custom attributes.
 (Optional, object)
 Assigns an index to nodes that have _all_ of the specified custom attributes.
 
-[[ilm-allocate-examples]]
-==== Examples
-
-[[ilm-allocate-change-replicas]]
-===== Change number of replicas
+[[ilm-allocate-ex]]
+==== Example
 
 The allocate action in the following policy changes the index's number of replicas to `2`. 
-Allocation rules are unchanged.
+The index allocation rules are not changed.
 
 [source,console]
 --------------------------------------------------
@@ -74,13 +68,13 @@ PUT _ilm/policy/my_policy
 }
 --------------------------------------------------
 
-[[ilm-allocate-assign-index-attribute]]
+[[ilm-allocate-assign-index-attribute-ex]]
 ===== Assign index to nodes using a custom attribute
 
 The allocate action in the following policy assigns the index to nodes 
 that have a `box_type` of _hot_ or _warm_.
 
-To designate a node's _box_type_, you set a custom attribute in the node configuration.
+To designate a node's `box_type`, you set a custom attribute in the node configuration.
 For example, set `node.attr.box_type: hot` in `elasticsearch.yml`. 
 For more information, see <<index-allocation-filters>>.
 
@@ -104,14 +98,14 @@ PUT _ilm/policy/my_policy
 }
 --------------------------------------------------
 
-[[ilm-allocate-assign-index-node]]
+[[ilm-allocate-assign-index-node-ex]]
 ===== Assign index to a specific node and update replica settings
 
 The allocate action in the following policy updates the index to have one replica per shard 
 and be allocated to nodes that have a `box_type` of _cold_. 
 
-To designate a node's _box_type_, you set a custom attribute in the node configuration.
-For example, set `node.attr.box_type: hot` in `elasticsearch.yml`. 
+To designate a node's `box_type`, you set a custom attribute in the node configuration.
+For example, set `node.attr.box_type: cold` in `elasticsearch.yml`. 
 For more information, see <<index-allocation-filters>>.
 
 [source,console]

docs/reference/ilm/actions/ilm-delete.asciidoc

@@ -6,16 +6,17 @@ Phases allowed: delete.
 
 Permanently removes the index.
 
-[[ilm-delete-action-options]]
-==== Delete
+[[ilm-delete-options]]
+==== Options
 
 `delete_searchable_snapshot`::
 (Optional, boolean)
 Deletes the searchable snapshot created in the cold phase. 
 Defaults to `true`.
-This is applicable when the <<ilm-searchable-snapshot-action>> is used in the cold phase.
+This option is applicable when the <<ilm-searchable-snapshot-action,searchable
+snapshot>> action is used in the cold phase.
 
-[[ilm-delete-action-example]]
+[[ilm-delete-action-ex]]
 ==== Example
 
 [source,console]

docs/reference/ilm/actions/ilm-forcemerge.asciidoc

@@ -4,22 +4,20 @@
 
 Phases allowed: hot, warm.
 
-NOTE: The index is made read-only when this action is run.
-See <<dynamic-index-settings,`index.blocks.write`>>.
+<<indices-forcemerge,Force merges>> the index into 
+the specified maximum number of <<indices-segments,segments>>.
 
-NOTE: If the `forcemerge` action is used in the `hot` phase, the `rollover` action *must* be preset.
-{ilm-init} validates this predicate and will refuse a policy with a forcemerge in the hot phase without a
-rollover action.
+This action makes the index <<dynamic-index-settings,read-only>>.
 
-The force merge action <<indices-forcemerge,force merges>> the index into a
-specified maximum number of <<indices-segments,segments>>.
+To use the `forcemerge` action in the `hot` phase, the `rollover` action *must* be present.
+If no rollover action is configured, {ilm-init} will reject the policy. 
 
 [[ilm-forcemerge-options]]
-==== Force merge options
+==== Options
 
 `max_num_segments`::
 (Required, integer) 
-The number of segments to merge to. To fully merge the index, set it to `1`
+Number of segments to merge to. To fully merge the index, set to `1`.
 
 `codec`::
 (Optional, string)   
@@ -28,12 +26,13 @@ Use the `best_compression` codec. Valid values: `best_compression`.
 [WARNING]
 ======
 Setting `"codec": "best_compression"` in the {ilm-init} forcemerge action causes {ilm-int} to
-<<indices-close,close>> and then <<indices-open-close,re-open>> the index prior to the forcemerge.
+<<indices-close,close>> and then <<indices-open-close,re-open>> the index prior to the force merge.
 During this time, the index is unavailable for both read and write operations.
 ======
 
-[[ilm-forcemerge-action-example]]
+[[ilm-forcemerge-action-ex]]
 ==== Example
+
 [source,console]
 --------------------------------------------------
 PUT _ilm/policy/my_policy

docs/reference/ilm/actions/ilm-freeze.asciidoc

@@ -4,15 +4,22 @@
 
 Phases allowed: cold.
 
-<<frozen-indices, freezes>> an index
-using the <<freeze-index-api, Freeze Index API>>.
+<<frozen-indices, Freezes>> an index to minimize its memory footprint.
 
-[[ilm-freeze-action-options]]
-==== Freeze options
+[IMPORTANT]
+================================
+ Freezing an index closes the index and reopens it within the same API call.
+ This means that for a short time no primaries are allocated.
+ The cluster will go red until the primaries are allocated.
+ This limitation might be removed in the future.
+================================
+
+[[ilm-freeze-options]]
+==== Options
 
 None.
 
-[[ilm-freeze-action-example]]
+[[ilm-freeze-ex]]
 ==== Example
 
 [source,console]
@@ -31,10 +38,3 @@ PUT _ilm/policy/my_policy
 }
 --------------------------------------------------
 
-[IMPORTANT]
-================================
- Freezing an index closes the index and reopens it within the same API call.
- This means that primaries will not be allocated for a short time. 
- The cluster will go red until the primaries are allocated.
- This limitation might be removed in the future.
-================================

docs/reference/ilm/actions/ilm-readonly.asciidoc

@@ -1,17 +1,17 @@
 [role="xpack"]
 [[ilm-readonly]]
-=== Read-only
+=== Read only
 
 Phases allowed: warm.
 
-Sets an index as read-only. See <<dynamic-index-settings,`index.blocks.write`>>.
+Makes the index <<dynamic-index-settings,read-only>>.
 
-[[ilm-read-only-action-options]]
-==== Read-only options
+[[ilm-read-only-options]]
+==== Options
 
 None.
 
-[[ilm-read-only-action-example]]
+[[ilm-read-only-ex]]
 ==== Example
 
 [source,console]

docs/reference/ilm/actions/ilm-rollover.asciidoc

@@ -38,9 +38,9 @@ PUT my_index-000001
 --------------------------------------------------
 
 [[ilm-rollover-options]]
-==== Rollover options
+==== Options
 
-You must specify at least one rollover option. 
+You must specify at least one rollover condition. 
 An empty rollover action is invalid.
 
 `max_size`::
@@ -55,10 +55,10 @@ Triggers roll over after the specified maximum number of documents in the index
 (Optional,  <<time-units, time units>>)  
 Triggers roll over after the maximum elapsed time from index creation is reached. 
 
-[[ilm-rollover-examples]]
-==== Examples
+[[ilm-rollover-ex]]
+==== Example
 
-[[ilm-rollover-size]]
+[[ilm-rollover-size-ex]]
 ===== Roll over based on index size
 
 This example rolls the index over when it is at least 100 gigabytes.
@@ -81,11 +81,10 @@ PUT _ilm/policy/my_policy
 }
 --------------------------------------------------
 
-[ilm-rollover-documents]]
+[ilm-rollover-documents-ex]]
 ===== Roll over based on document count
 
-This example rolls the index over when it contains at least
-one hundred million documents.
+This example rolls the index over when it contains at least one hundred million documents.
 
 [source,console]
 --------------------------------------------------
@@ -105,11 +104,10 @@ PUT _ilm/policy/my_policy
 }
 --------------------------------------------------
  
-[ilm-rollover-age]]
+[ilm-rollover-age-ex]]
 ===== Roll over based on index age
 
-This example rolls the index over when it has been created at least
-7 days ago.
+This example rolls the index over if it was created at least 7 days ago.
 
 [source,console]
 --------------------------------------------------
@@ -129,12 +127,12 @@ PUT _ilm/policy/my_policy
 }
 --------------------------------------------------
 
-[ilm-rollover-conditions]]
+[ilm-rollover-conditions-ex]]
 ===== Roll over using multiple conditions
 
-When you specify multiple rollover options, 
-the index is rolled over when any of the conditions are met.
-This example rolls the index over if it is at least 7 days old or at least 100 GB. 
+When you specify multiple rollover conditions, 
+the index is rolled over when _any_ of the conditions are met.
+This example rolls the index over if it is at least 7 days old or at least 100 gigabytes. 
 
 [source,console]
 --------------------------------------------------
@@ -155,7 +153,7 @@ PUT _ilm/policy/my_policy
 }
 --------------------------------------------------
 
-[ilm-rollover-block]]
+[ilm-rollover-block-ex]]
 ===== Rollover condition blocks phase transition
 
 The rollover action only completes if one of its conditions is met. 

docs/reference/ilm/actions/ilm-searchable-snapshot.asciidoc

@@ -4,22 +4,22 @@
 
 Phases allowed: cold.
 
-This action takes a snapshot of the managed index in the configured repository
+Takes a snapshot of the managed index in the configured repository
 and mounts it as a searchable snapshot.
 
 By default, this snapshot is deleted by the <<ilm-delete-action, delete action>> in the delete phase.
 To keep the snapshot, set `delete_searchable_snapshot` to `false` in the delete action.
 
 [[ilm-searchable-snapshot-options]]
-==== Searchable snapshot options
+==== Options
 
 `snapshot_repository`::
 (Required, string)
 Specifies where to store the snapshot. 
 See <<snapshots-register-repository>> for more information.
 
-[[ilm-searchable-snapshot-example]]
-==== Example
+[[ilm-searchable-snapshot-ex]]
+==== Examples
 [source,console]
 --------------------------------------------------
 PUT _ilm/policy/my_policy

docs/reference/ilm/actions/ilm-set-priority.asciidoc

@@ -11,10 +11,10 @@ Higher priority indices are recovered before indices with lower priorities follo
 Generally, indexes in the hot phase should have the highest value and
 indexes in the cold phase should have the lowest values. 
 For example: 100 for the hot phase, 50 for the warm phase, and 0 for the cold phase.
-Indices that don't set this value have an implicit default priority of 1.
+Indices that don't set this value have a default priority of 1.
 
 [[ilm-set-priority-options]]
-==== Set priority options
+==== Options
 
 `priority`::
 (Required, integer)  
@@ -22,7 +22,7 @@ The priority for the index.
 Must be 0 or greater.
 Set to `null` to remove the priority.
 
-[[ilm-set-priority-example]]
+[[ilm-set-priority-ex]]
 ==== Example
 
 [source,console]

docs/reference/ilm/actions/ilm-shrink.asciidoc

@@ -25,11 +25,11 @@ then converts the follower index into a regular index with the
 ==== Shrink options
 `number_of_shards`::
 (Required, integer) 
-The number of shards to shrink to. 
+Number of shards to shrink to. 
 Must be a factor of the number of shards in the source index.
 
 
-[[ilm-shrink-example]]
+[[ilm-shrink-ex]]
 ==== Example
  
 [source,console]

docs/reference/ilm/actions/ilm-unfollow.asciidoc

@@ -33,12 +33,12 @@ Once these conditions are met, unfollow performs the following operations:
 * Unfollows the leader index.
 * Opens the follower index (which is at this point is a regular index).
 
-[[ilm-unfollow-action-options]]
-==== Unfollow options
+[[ilm-unfollow-options]]
+==== Options
 
 None.
 
-[[ilm-unfollow-action-example]]
+[[ilm-unfollow-ex]]
 ==== Example
 
 [source,console]

docs/reference/ilm/actions/ilm-wait-for-snapshot.asciidoc

@@ -1,19 +1,21 @@
 [role="xpack"]
 [[ilm-wait-for-snapshot]]
-=== Wait For Snapshot
+=== Wait for snapshot
 
 Phases allowed: delete.
 
-The Wait For Snapshot Action waits for defined SLM policy to be executed to ensure that snapshot of index exists before
-deletion.
+Waits for the specified {slm-init} policy to be executed before removing the index.
+This ensures that a snapshot of the deleted index is available. 
 
 [[ilm-wait-for-snapshot-options]]
-.Wait For Snapshot
-[options="header"]
-|======
-| Name                 | Required  | Default             | Description
-| `policy`             | yes       | -                   | SLM policy name that this action should wait for
-|======
+==== Options
+
+`policy`::
+(Required, string)
+Name of the {slm-init} policy that the delete action should wait for.
+
+[[ilm-wait-for-snapshot-ex]]
+==== Example
 
 [source,console]
 --------------------------------------------------