[DOCS] Updates terms in anomaly detection job APIs (#44839)

lcawl · lcawl · commit 96dfd63b075c · 2019-07-25T13:17:48.000-07:00
diff --git a/docs/java-rest/high-level/ml/close-job.asciidoc b/docs/java-rest/high-level/ml/close-job.asciidoc
@@ -4,14 +4,12 @@
 :response: CloseJobResponse
 --
 [id="{upid}-{api}"]
-=== Close Job API
+=== Close {anomaly-job} API
 
-The Close Job API provides the ability to close {ml} jobs in the cluster.
-It accepts a +{request}+ object and responds
-with a +{response}+ object.
+Closes {anomaly-jobs} in the cluster. It accepts a +{request}+ object and responds with a +{response}+ object.
 
 [id="{upid}-{api}-request"]
-==== Close Job Request
+==== Close {anomaly-job} request
 
 A +{request}+ object gets created with an existing non-null `jobId`.
 
@@ -28,7 +26,7 @@ which has not responded to its initial close request.
 execution should wait for the job to be closed.
 
 [id="{upid}-{api}-response"]
-==== Close Job Response
+==== Close {anomaly-job} response
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
diff --git a/docs/java-rest/high-level/ml/delete-job.asciidoc b/docs/java-rest/high-level/ml/delete-job.asciidoc
@@ -4,10 +4,12 @@
 :response: AcknowledgedResponse
 --
 [id="{upid}-{api}"]
-=== Delete Job API
+=== Delete {anomaly-job} API
+
+Deletes an {anomaly-job} that exists in the cluster.
 
 [id="{upid}-{api}-request"]
-==== Delete Job Request
+==== Delete {anomaly-job} request
 
 A +{request}+ object requires a non-null `jobId` and can optionally set `force`.
 
@@ -17,7 +19,7 @@ include-tagged::{doc-tests-file}[{api}-request]
 ---------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
-==== Optional Arguments
+==== Optional arguments
 
 The following arguments are optional:
 
@@ -33,21 +35,24 @@ Defaults to `false`.
 ---------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-request-wait-for-completion]
 ---------------------------------------------------
-<1> Use to set whether the request should wait until the operation has completed before returning.
-Defaults to `true`.
+<1> Use to set whether the request should wait until the operation has completed
+before returning. Defaults to `true`.
 
 
 [id="{upid}-{api}-response"]
-==== Delete Job Response
+==== Delete {anomaly-job} response
 
-The returned +{response}+ object indicates the acknowledgement of the job deletion or
-the deletion task depending on whether the request was set to wait for completion:
+The returned +{response}+ object indicates the acknowledgement of the job
+deletion or the deletion task depending on whether the request was set to wait
+for completion:
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-response]
 ---------------------------------------------------
-<1> whether was job deletion was acknowledged or not; will be `null` when set not to wait for completion
-<2> the id of the job deletion task; will be `null` when set to wait for completion
+<1> whether was job deletion was acknowledged or not; will be `null` when set
+not to wait for completion
+<2> the id of the job deletion task; will be `null` when set to wait for
+completion
 
 include::../execution.asciidoc[]
diff --git a/docs/java-rest/high-level/ml/open-job.asciidoc b/docs/java-rest/high-level/ml/open-job.asciidoc
@@ -4,14 +4,13 @@
 :response: OpenJobResponse
 --
 [id="{upid}-{api}"]
-=== Open Job API
+=== Open {anomaly-job} API
 
-The Open Job API provides the ability to open {ml} jobs in the cluster.
-It accepts a +{request}+ object and responds
-with a +{response}+ object.
+Opens {anomaly-jobs} in the cluster. It accepts a +{request}+ object and
+responds with a +{response}+ object.
 
 [id="{upid}-{api}-request"]
-==== Open Job Request
+==== Open {anomaly-job} request
 
 An +{request}+ object gets created with an existing non-null `jobId`.
 
@@ -24,7 +23,7 @@ include-tagged::{doc-tests-file}[{api}-request]
 execution should wait for the job to be opened.
 
 [id="{upid}-{api}-response"]
-==== Open Job Response
+==== Open {anomaly-job} response
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
diff --git a/docs/java-rest/high-level/ml/put-job.asciidoc b/docs/java-rest/high-level/ml/put-job.asciidoc
@@ -4,27 +4,26 @@
 :response: PutJobResponse
 --
 [id="{upid}-{api}"]
-=== Put Job API
+=== Put {anomaly-job} API
 
-The Put Job API can be used to create a new {ml} job
-in the cluster. The API accepts a +{request}+ object
+Creates a new {anomaly-job} in the cluster. The API accepts a +{request}+ object
 as a request and returns a +{response}+.
 
 [id="{upid}-{api}-request"]
-==== Put Job Request
+==== Put {anomaly-job} request
 
 A +{request}+ requires the following argument:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
-<1> The configuration of the {ml} job to create as a `Job`
+<1> The configuration of the {anomaly-job} to create as a `Job`
 
 [id="{upid}-{api}-config"]
-==== Job Configuration
+==== Job configuration
 
-The `Job` object contains all the details about the {ml} job
+The `Job` object contains all the details about the {anomaly-job}
 configuration.
 
 A `Job` requires the following arguments:
@@ -39,9 +38,9 @@ include-tagged::{doc-tests-file}[{api}-config]
 <4> Optionally, a human-readable description
 
 [id="{upid}-{api}-analysis-config"]
-==== Analysis Configuration
+==== Analysis configuration
 
-The analysis configuration of the {ml} job is defined in the `AnalysisConfig`.
+The analysis configuration of the {anomaly-job} is defined in the `AnalysisConfig`.
 `AnalysisConfig` reflects all the configuration
 settings that can be defined using the REST API.
 
@@ -86,7 +85,7 @@ include-tagged::{doc-tests-file}[{api}-analysis-config]
 <3> The bucket span
 
 [id="{upid}-{api}-data-description"]
-==== Data Description
+==== Data description
 
 After defining the analysis config, the next thing to define is the
 data description, using a `DataDescription` instance. `DataDescription`
diff --git a/docs/reference/ml/anomaly-detection/apis/close-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/close-job.asciidoc
@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="platinum"]
 [[ml-close-job]]
-=== Close jobs API
+=== Close {anomaly-jobs} API
 ++++
 <titleabbrev>Close jobs</titleabbrev>
 ++++
 
-Closes one or more jobs.
+Closes one or more {anomaly-jobs}.
 A job can be opened and closed multiple times throughout its lifecycle.
 
 A closed job cannot receive data or perform analysis
@@ -25,9 +25,9 @@ operations, but you can still explore and navigate results.
 [[ml-close-job-desc]]
 ==== {api-description-title}
 
-You can close multiple jobs in a single API request by using a group name, a
-comma-separated list of jobs, or a wildcard expression. You can close all jobs
-by using `_all` or by specifying `*` as the `<job_id>`.
+You can close multiple {anomaly-jobs} in a single API request by using a group
+name, a comma-separated list of jobs, or a wildcard expression. You can close
+all jobs by using `_all` or by specifying `*` as the `<job_id>`.
 
 When you close a job, it runs housekeeping tasks such as pruning the model history,
 flushing buffers, calculating final results and persisting the model snapshots.
@@ -52,9 +52,9 @@ results the job might have recently produced or might produce in the future.
 [[ml-close-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
-  (string) Identifier for the job. It can be a job identifier, a group name, or
-  a wildcard expression.
+`<job_id>`::
+  (Required, string) Identifier for the {anomaly-job}. It can be a job
+  identifier, a group name, or a wildcard expression.
 
 [[ml-close-job-query-parms]]
 ==== {api-query-parms-title}
diff --git a/docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc
@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="platinum"]
 [[ml-delete-job]]
-=== Delete jobs API
+=== Delete {anomaly-jobs} API
 ++++
 <titleabbrev>Delete jobs</titleabbrev>
 ++++
 
-Deletes an existing anomaly detection job.
+Deletes an existing {anomaly-job}.
 
 [[ml-delete-job-request]]
 ==== {api-request-title}
@@ -18,23 +18,23 @@ Deletes an existing anomaly detection job.
 
 All job configuration, model state and results are deleted.
 
-IMPORTANT:  Deleting a job must be done via this API only. Do not delete the
-job directly from the `.ml-*` indices using the Elasticsearch delete document
+IMPORTANT:  Deleting an {anomaly-job} must be done via this API only. Do not
+delete the job directly from the `.ml-*` indices using the {es} delete document
 API. When {es} {security-features} are enabled, make sure no `write` privileges
 are granted to anyone over the `.ml-*` indices.
 
 Before you can delete a job, you must delete the {dfeeds} that are associated
-with it. See <<ml-delete-datafeed,Delete {dfeeds-cap}>>. Unless the `force` parameter
-is used the job must be closed before it can be deleted.
+with it. See <<ml-delete-datafeed,Delete {dfeeds-cap}>>. Unless the `force`
+parameter is used the job must be closed before it can be deleted.
 
 It is not currently possible to delete multiple jobs using wildcards or a comma
 separated list.
 
 [[ml-delete-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-  (string) Identifier for the job
+`<job_id>`::
+  (Required, string) Identifier for the {anomaly-job}.
 
 [[ml-delete-job-query-parms]]
 ==== {api-query-parms-title}
diff --git a/docs/reference/ml/anomaly-detection/apis/open-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/open-job.asciidoc
@@ -1,14 +1,12 @@
 [role="xpack"]
 [testenv="platinum"]
 [[ml-open-job]]
-=== Open jobs API
+=== Open {anomaly-jobs} API
 ++++
 <titleabbrev>Open jobs</titleabbrev>
 ++++
 
-Opens one or more jobs.
-A job must be opened in order for it to be ready to receive and analyze data.
-A job can be opened and closed multiple times throughout its lifecycle.
+Opens one or more {anomaly-jobs}.
 
 [[ml-open-job-request]]
 ==== {api-request-title}
@@ -18,6 +16,10 @@ A job can be opened and closed multiple times throughout its lifecycle.
 [[ml-open-job-desc]]
 ==== {api-description-title}
 
+An {anomaly-job} must be opened in order for it to be ready to receive and
+analyze data. It can be opened and closed multiple times throughout its
+lifecycle.
+
 When you open a new job, it starts with an empty model.
 
 When you open an existing job, the most recent model state is automatically loaded.
@@ -26,8 +28,8 @@ The job is ready to resume its analysis from where it left off, once new data is
 [[ml-open-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-(string) Identifier for the job
+`<job_id>`::
+  (Required, string) Identifier for the {anomaly-job}.
 
 [[ml-open-job-request-body]]
 ==== {api-request-body-title}
diff --git a/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc b/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc
@@ -2,10 +2,8 @@
 [testenv="platinum"]
 [[ml-put-job]]
 === Create {anomaly-jobs} API
-
-[subs="attributes"]
 ++++
-<titleabbrev>Create {anomaly-jobs}</titleabbrev>
+<titleabbrev>Create jobs</titleabbrev>
 ++++
 
 Instantiates an {anomaly-job}.
