[Alerting][Docs] Adding template for documenting alert and action types

docs/action-type-template.asciidoc

@@ -0,0 +1,71 @@
+[[<ACTION-TYPE>-action-type]]
+=== <ACTION-TYPE> action
+
+Include a short description of the action type.
+
+[float]
+[[<ACTION-TYPE>-connector-configuration]]
+==== Connector configuration
+
+<ACTION-TYPE> connectors have the following configuration properties.
+
+////
+List of user-facing connector configurations. This should align with the fields available in the Create connector flyout form for this action type.
+////
+
+Property1:: A short description of this property.
+Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
+
+[float]
+[[Preconfigured-<ACTION-TYPE>-configuration]]
+==== Preconfigured action type
+
+////
+Example preconfigured format for this action type
+////
+
+[source,text]
+--
+ my-<ACTION-TYPE>:
+   name: preconfigured-<ACTION-TYPE>-action-type
+   actionTypeId: .<ACTION-TYPE>
+   config: <1>
+     property1: value1
+     property2: value2
+   secrets: <2>
+     property3: value3
+--
+
+[float]
+[[<ACTION-TYPE>-connector-config-properties]]
+////
+List of properties from the ConfigSchema and SecretsSchema for this action type.
+////
+<1> Config defines information for the action type and contains the following properties.
++
+`property1`:: A short description of this property.
++
+`property2`:: A short descriptionn of this property.
+
+<2> Secrets defines sensitive information for the action type and contains the following properties.
++
+`property3`:: A short descriptionn of this property.
+
+[float]
+[[<ACTION-TYPE>-action-configuration]]
+==== Action configuration
+
+<ACTION-TYPE> actions have the following configuration properties.
+
+////
+List of user-facing action configurations. This should align with the fields available in the Action section of the Create/Update alert flyout.
+////
+
+Property1:: A short description of this property.
+Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
+
+////
+Optional - additional configuration details here
+[[configuring-<ACTION-TYPE>]]
+==== Configuring <ACTION-TYPE>
+////

docs/alert-type-template.asciidoc

@@ -0,0 +1,47 @@
+[[alert-type-<ALERT TYPE>]]
+=== <ALERT TYPE>
+
+Include a short description of the alert type.
+
+[float]
+==== Create the alert
+
+Fill in the <<defining-alerts-general-details, alert details>>, then select *<ALERT TYPE>*.
+
+////
+Optional, include a screenshot
+[role="screenshot"]
+image::user/alerting/images/alert-types-<ALERT TYPE>-select.png[Choose an <ALERT TYPE> alert type]
+////
+
+[float]
+==== Conditions
+
+Include all of the conditions for this alert type and a short description of each.
+
+////
+Optional, include a screenshot
+[role="screenshot"]
+image::user/alerting/images/alert-types-<ALERT TYPE>-conditions.png[Conditions for <ALERT TYPE> alert type]
+////
+
+Condition1:: This is a condition the user must define.
+Condition2:: This is another condition the user must define.
+
+[float]
+==== Action variables
+
+When the <ALERT TYPE> alert condition is met, the following variables are available to each action, in addition to the <<defining-alerts-actions-variables, variables common to all alerts>>:
+
+`context.variableA`:: A short description of the context variable defined by the alert type.
+`context.variableB`:: A short description of the context variable defined by the alert type with an example. Example: `this is what variableB outputs`.
+
+<<defining-alerts-actions-details, Add an action>> to the alert to use these variables.
+
+////
+Optional, include a step-by-step example for creating this alert 
+[float]
+==== Example
+
+In this section, you will use the {kib} <<add-sample-data, weblog sample dataset>> to setup and tune the conditions on an <ALERT TYPE> alert. For this example, we want to detect when <DESCRIBE THE CONDITIONS>.
+////

docs/user/alerting/action-types/email.asciidoc

@@ -10,14 +10,15 @@ NOTE: For emails to have a footer with a link back to {kib}, set the <<server-pu
 [[email-connector-configuration]]
 ==== Connector configuration
 
-Email connectors have the following configuration properties:
+Email connectors have the following configuration properties.
 
 Name::      The name of the connector. The name is used to identify a  connector in the management UI connector listing, or in the connector list when configuring an action.
 Sender::    The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name <user@host-name>"` format. See the https://nodemailer.com/message/addresses/[Nodemailer address documentation] for more information.
 Host::      Host name of the service provider. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure this hostname is added to the allowed hosts.
 Port::      The port to connect to on the service provider.
 Secure::    If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information.  If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command.
-User::  Username for login type authentication.
+Require authentication:: If true, a username and password for login type authentication must be provided.
+Username::  Username for login type authentication.
 Password::  Password for login type authentication.
 
 [float]
@@ -29,66 +30,49 @@ Password::  Password for login type authentication.
  my-email:
    name: preconfigured-email-action-type
    actionTypeId: .email
-   config:
+   config: <1>
      from: testsender@test.com
      host: validhostname
      port: 8080
      secure: false
-   secrets:
+   secrets: <2>
      user: testuser
      password: passwordkeystorevalue
 --
 
-[[email-connector-config-properties]]
-**`config`** defines the action type specific to the configuration and contains the following properties:
-
-[cols="2*<"]
-|===
-
-| `service`
-| The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the (https://nodemailer.com/usage/using-gmail/)[Nodemailer Gmail documentation].
-
-| `from`
-| An email address that corresponds to *Sender*.
-
-| `host`
-| A string that corresponds to *Host*.
-
-| `port`
-| A number that corresponds to *Port*.
-
-| `secure`
-| A boolean that corresponds to *Secure*.
-
-| `hasAuth`
-| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
-
-|===
-
-**`secrets`** defines sensitive information for the action type and contains the following properties:
-
-[cols="2*<"]
-|===
-
-| `user`
-| A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
-
-| `password`
-| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
-
-|===
+<1> Config defines information for the action type and contains the following properties.
++
+`service`:: The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the (https://nodemailer.com/usage/using-gmail/)[Nodemailer Gmail documentation].
++
+`from`:: An email address that corresponds to *Sender*.
++
+`host`:: A string that corresponds to *Host*.
++
+`port`:: A number that corresponds to *Port*.
++
+`secure`:: A boolean that corresponds to *Secure*.
++
+`hasAuth`:: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
+
+<2> Secrets defines sensitive information for the action type and contains the following properties.
++
+`user`:: A string that corresponds to *Username*. Required if `hasAuth` is set to `true`.
++
+`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
+'''
 
+[float]
 [[email-action-configuration]]
 ==== Action configuration
 
-Email actions have the following configuration properties:
+Email actions have the following configuration properties.
 
 To, CC, BCC::    Each is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
 Subject::       The subject line of the email.
 Message::       The message text of the email. Markdown format is supported.
 
 [[configuring-email]]
-==== Configuring email accounts
+==== Configuring email accounts for well-known services
 
 The email action can send email using many popular SMTP email services.
 

docs/user/alerting/action-types/index.asciidoc

@@ -8,7 +8,7 @@ The index action type will index a document into {es}. See also the {ref}/indice
 [[index-connector-configuration]]
 ==== Connector configuration
 
-Index connectors have the following configuration properties:
+Index connectors have the following configuration properties.
 
 Name::      The name of the connector. The name is used to identify a  connector in the management UI connector listing, or in the connector list when configuring an action.
 Index::     The {es} index to be written to.
@@ -24,35 +24,26 @@ Execution time field::  This field will be automatically set to the time the ale
  my-index:
    name: action-type-index
    actionTypeId: .index
-   config:
+   config: <1>
      index: .kibana
      refresh: true
      executionTimeField: somedate
 --
 
-[[index-connector-config-properties]]
-**`config`** defines the action type specific to the configuration and contains the following properties:
-
-[cols="2*<"]
-|===
-
-|`index`
-| A string that corresponds to *Index*.
-
-|`refresh`
-| A boolean that corresponds to *Refresh*. Defaults to `false`.
-
-|`executionTimeField`
-| A string that corresponds to *Execution time field*.
-
-|===
-
+<1> Config defines information for the action type and contains the following properties.
++
+`index`:: A string that corresponds to *Index*.
++
+`refresh`:: A boolean that corresponds to *Refresh*. Defaults to `false`.
++
+`executionTimeField`:: A string that corresponds to *Execution time field*.
+'''
 
 [float]
 [[index-action-configuration]]
 ==== Action configuration
 
-Index actions have the following properties:
+Index actions have the following properties.
 
 Document::  The document to index in JSON format.
 

docs/user/alerting/action-types/jira.asciidoc

@@ -8,7 +8,7 @@ The Jira action type uses the https://developer.atlassian.com/cloud/jira/platfor
 [[jira-connector-configuration]]
 ==== Connector configuration
 
-Jira connectors have the following configuration properties:
+Jira connectors have the following configuration properties.
 
 Name::      The name of the connector. The name is used to identify a  connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
 URL::       Jira instance URL.
@@ -25,45 +25,32 @@ API token (or password)::  Jira API authentication token (or password) for HTTP
  my-jira:
    name: preconfigured-jira-action-type
    actionTypeId: .jira
-   config:
+   config: <1>
      apiUrl: https://elastic.atlassian.net
      projectKey: ES
-   secrets:
+   secrets: <2>
      email: testuser
      apiToken: tokenkeystorevalue
 --
 
-[[jira-connector-config-properties]]
-**`config`** defines the action type specific to the configuration and contains the following properties:
+<1> Config defines information for the action type and contains the following properties.
++
+`apiUrl`:: An address that corresponds to *URL*.
++
+`projectKey`:: A key that corresponds to *Project Key*.
 
-[cols="2*<"]
-|===
-
-| `apiUrl`
-| An address that corresponds to *URL*.
-
-| `projectKey`
-| A key that corresponds to *Project Key*.
-
-|===
-
-**`secrets`** defines sensitive information for the action type and contains the following properties:
-
-[cols="2*<"]
-|===
-
-| `email`
-| A string that corresponds to *Email*.
-
-| `apiToken`
-| A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
-
-|===
+<2> Secrets defines sensitive information for the action type and contains the following properties.
++
+`email`:: A string that corresponds to *Email*.
++
+`apiToken`:: A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
+'''
 
+[float]
 [[jira-action-configuration]]
 ==== Action configuration
 
-Jira actions have the following configuration properties:
+Jira actions have the following configuration properties.
 
 Subaction::        The subaction to perform: `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`.
 Subaction params:: The parameters of the subaction.