docs(managed-delivery): Document ability to use interactive Slack not…

…ifications (#1711)

* docs(managed-delivery): Document ability to use interactive Slack notifications

* Address review feedback + minor improvements

guides/user/managed-delivery/delivery-configs/index.md

@@ -12,7 +12,7 @@ _**Prerequisite:** read and complete the [getting started](/guides/user/managed-
 
 ## What is a Delivery Config?
 
-A **delivery config** allows you to group resources together in a single file (`spinnaker.yml`) and specify how these resources work together to promote an **artifact** between **environments**.
+A **delivery config** allows you to group resources together in a single file (e.g. `spinnaker.yml`) and specify how these resources work together to promote an **artifact** between **environments**.
 
 ### Artifacts
 

guides/user/managed-delivery/environment-constraints/index.md

@@ -287,9 +287,83 @@ If set, overrides the `defaults.constraint.canary.storage-account` property. Not
 
 Apart from the [depends-on](#depends-on) constraint, all constraint types either expect interaction from a user 
 (in the case of [manual-judgement](#manual-judgement)) or can have their automated judgements overruled by a
-user. The following API endpoints are currently available to interact with constraints.
+user.
 
-### Reading status of pending and recent constraints
+### Approving or rejecting Manual Judgement constraints from Slack
+If your operator has configured [Slack app](https://api.slack.com/start/overview) integration with Spinnaker, then a
+very convenient way to approve managed deployments gated by a Manual Judgement constraint is to use interactive Slack
+notifications.
+
+All you need to do is [set up Slack notifications](/guides/user/managed-delivery/delivery-configs/#environment-notifications) in your delivery config, which will enable interactive notifications
+to a Slack channel of your choice, where you can simply click a button to approve or reject the deployment of the
+artifact into the environment.
+
+Consider the following simplified delivery config:
+```yaml
+name: myspinapp
+application: myspinapp
+serviceAccount: myteam@mycompany.com
+artifacts:
+- name: myspinapp
+  type: deb
+environments:
+- name: test
+  constraints:
+  - type: manual-judgement
+  notifications:
+  - type: slack
+    address: "#myteam"
+    frequency: verbose
+  resources:
+  - apiVersion: bakery.spinnaker.netflix.com/v1
+    kind: image
+    spec:
+      artifactName: myspinapp
+      baseLabel: RELEASE
+      baseOs: xenial
+      regions:
+      - us-east-1
+      storeType: EBS
+      application: myspinapp  
+  - apiVersion: "ec2.spinnaker.netflix.com/v1"
+    kind: "cluster"
+    spec:
+      moniker:
+        app: "myspinapp"
+      imageProvider:
+        deliveryArtifact:
+          name: "myspinapp"
+          type: "deb"
+      locations:
+        account: "test"
+        regions:
+        - name: "us-east-1"
+```
+
+Upon evaluating whether a new Debian artifact for `myspinapp` should be deployed into the `test` environment,
+Spinnaker will gate the deployment on the `manual-judgement` constraint and send a notification that looks like
+the following to the `#myteam` Slack channel.
+{%
+  include
+  figure
+  image_path="./md-manual-judgment-notification.png"
+%}
+
+Once a user in the channel clicks on the `Approve` button, the notification changes to reflect the approval:
+{%
+  include
+  figure
+  image_path="./md-manual-judgment-approved.png"
+%}
+
+> :warning: Note that the `frequency` setting for notifications does not affect this behavior -- interactive
+> notifications will always be sent unless your operator has chosen to disable this feature entirely on your
+> company's instance of Spinnaker.
+
+### APIs to interact with constraints
+In addition to Slack integration, the following API endpoints are currently available to interact with constraints.
+
+#### Reading status of pending and recent constraints
 
 - **`GET`** `https://gate/managed/delivery-configs/{delivery-config-name}/environment/{environment-name}/constraints?limit=20`
 
@@ -307,7 +381,7 @@ Returns: `List<ConstraintState>` consisting of:
   Map<String, Object> attributes;
 ```
 
-### Setting or Overriding Constraint State
+#### Setting or Overriding Constraint State
 
 - **`POST`** `https://gate/managed/delivery-configs/{delivery-config-name}/environment/{environment-name}/constraint`
 

guides/user/managed-delivery/getting-started/index.md

@@ -21,10 +21,10 @@ You can pick a new piece of infrastructure that you want to create (a new load b
 We recommend creating a new security group to test things out.
 This guide will walk you through creating a new managed security group.
 
-First, you'll create a YAML file to store your delivery config in.
-Then, you'll set up a Spinnaker pipeline to submit that YAML file to Spinnaker.
-Finally, you'll watch Spinnaker take actions to make your resource exist.
-
+Here are the steps you'll complete:
+1. First, you'll create a YAML file to store your delivery config in.
+2. Then, you'll set up a Spinnaker pipeline to submit that YAML file to Spinnaker.
+3. Finally, you'll watch Spinnaker take actions to make your resource exist.
 
 ## Background
 
@@ -33,10 +33,13 @@ These resources are security groups, load balancers, and clusters.
 To create these resources you manually define them by clicking the `create` button in the Spinnaker UI.
 
 Managed Delivery changes this interaction.
-To define resources that Spinnaker manages, you'll create a YAML "delivery config" file specifying the desired state of your infrastructure resources.
-"Desired state" is a new-to-Spinnaker phrase that means you're specifying **what** you want your infrastructure to always look like, regardless of **how** Spinnaker decides to make it look that way.
+To define resources that Spinnaker manages, you'll create a YAML-based "delivery config" file specifying the desired state of your infrastructure resources.
+"Desired state" is a new concept in Spinnaker that means you're specifying **what** you want your infrastructure to always look like, regardless of **how** Spinnaker decides to make it look that way.
 In practice, this desired state will often look like the configuration options you're used to defining through the Spinnaker UI.
 
+> :bulb: To learn more about delivery configs, check out <a href="/guides/user/managed-delivery/delivery-configs/" target="_blank">this section</a>
+> of the documentation.
+
 Once you create a YAML delivery config, you'll need to tell Spinnaker to manage it. 
 This is done by submitting the file to Spinnaker's API.
 You can submit a delivery config from your local machine, but that's not very traceable or repeatable.
@@ -51,7 +54,6 @@ All the instructions for this flow are captured in this doc.
 
 Let's get started!
 
-
 ## Prerequisites
 
 Spinnaker takes a lot of actions on your behalf, and we do that by using the permissions of a service account.
@@ -148,7 +150,7 @@ For example, my sample security group for my app `keeldemo` will have a moniker
 
 which will name the security group `keeldemo-md`.
 
-**STOP! Don't commit your delivery config yet! Just save it locally.**
+:stop_sign: **STOP! Don't commit your delivery config yet! Just save it locally.**
 
 
 ## Repository Permissions