Restructure docs regarding shipyard file

content/docs/0.8.x/automated_operations/remediation/index.md

@@ -8,6 +8,38 @@ keywords: [0.8.x-automated-operations]
 
 The remediation config describes a remediation workflow in a declarative manner. Hence, it only defines what needs to be done and leaves all the details to other components. 
 
+## Declare a remediation sequence in shipyard
+
+The definition of a remediation sequence is done in a so-called [Shipyard](../../manage/shipyard) file.
+
+**Example**: Simple shipyard file with a remediation sequence in a single stage
+```yaml
+apiVersion: "spec.keptn.sh/0.2.0"
+kind: "Shipyard"
+metadata:
+  name: "shipyard-sockshop"
+spec:
+  stages:
+    - name: "production"
+      sequences:
+        - name: "remediation"
+          triggeredOn:
+            - event: "production.remediation.finished"
+              selector:
+                match:
+                  evaluation.result: "fail"
+          tasks:
+            - name: "get-action"
+            - name: "action"
+            - name: "evaluation"
+              triggeredAfter: "10m"
+              properties:
+                timeframe: "10m"
+```
+
+*Note*: Remediations can also be used in combination with [multi stage delivery](../../continuous_delivery/multi_stage) workflows.
+
+
 ## Configure Remediation
 
 Below is an example of a declarative remediation config: 
@@ -96,4 +128,4 @@ spec:
 
     ```console
     keptn add-resource --project=sockshop --stage=production --service=serviceXYZ --resource=remediation.yaml --resourceUri=remediation.yaml
-    ```
+    ```

content/docs/0.8.x/continuous_delivery/multi_stage/index.md

@@ -5,23 +5,13 @@ weight: 1
 keywords: [0.8.x-cd]
 ---
 
-The definition of a multi-stage delivery manifests in a so-called **shipyard**. It can hold multiple stages with dedicated and opinionated delivery tasks to execute. Following this declarative approach, there is no need to write imperative pipeline code. Keptn takes the shipyard and creates a sequence for multi-stage delivery.
 
-## Declare Shipyard (before creating a project)
 
-* A shipyard is defined at the level of a project. This means that all services in a project share the same shipyard definition. 
+## Declare a multi-stage delivery sequence in shipyard
 
-* A shipyard defines the stages each deployment has to go through until it is released in the final stage, e.g., the production stage. 
+The definition of a multi-stage delivery manifests in a so-called [Shipyard](../../manage/shipyard) file. It can hold multiple stages with dedicated and opinionated delivery tasks to execute.
 
-* A shipyard can consist of any number of stages; but at least one. A stage must have at least the name property.
-
-* A stage can consist of any number of sequences; but at least one. 
-
-### Definition of Stage 
-
-A stage is declared by its name. This name will be used for the branch in the Git repository and Kubernetes namespace to which services at this stage will be deployed to. 
-
-**Example of a shipyard with three stages:**
+**Example**: Simple shipyard file with a delivery sequence in the two stages `dev` and `production`, whereas `dev` uses a direct deployment and `prod` uses blue-green deployment:
 
 ```yaml
 apiVersion: spec.keptn.sh/0.2.0
@@ -31,19 +21,27 @@ metadata:
 spec:
   stages:
     - name: "dev"
-    - name: "hardening"
+      sequences:
+      - name: "delivery"
+        tasks: 
+        - name: "deployment"
+          properties:
+            deploymentstrategy: "direct"
+        - name: "release"
+
     - name: "production"
+      sequences:
+      - name: "delivery"
+        triggeredOn:
+          - event: "dev.delivery.finished"
+        tasks: 
+        - name: "deployment"
+          properties:
+            deploymentstrategy: "blue_green_service"
+        - name: "release"
 ```
 
-### Definition of Sequence in a Stage
-
-After defining stages, sequences can be added to a stage. A sequence is an ordered list of tasks that are triggered sequentially. A `sequence` consists of the following properties:
-
-* `name`: A unique name of the sequence
-* `on` (optional): An array of events that trigger the sequence.
-* `tasks`: An array of tasks executed by the sequence in the declared order.
-
-**Example:** Extended shipyard with a delivery sequence in all three stage:
+**Example:** Extended shipyard with a delivery sequence in three stages `dev`, `hardening` and `production` in combination with tests:
 
 ```yaml
 apiVersion: spec.keptn.sh/0.2.0
@@ -57,67 +55,42 @@ spec:
       - name: "delivery"
         tasks: 
         - name: "deployment"
+          properties:
+            deploymentstrategy: "direct"
+        - name: "test"
+          properties:
+            teststrategy: "functional"
+        - name: "evaluation"
         - name: "release"
+
     - name: "hardening"
       sequences:
       - name: "delivery"
         triggeredOn:
           - event: "dev.delivery.finished"
         tasks: 
         - name: "deployment"
+          properties:
+            deploymentstrategy: "blue_green_service"
+        - name: "test"
+          properties:
+            teststrategy: "functional"
+        - name: "evaluation"
         - name: "release"
+
     - name: "production"
       sequences:
       - name: "delivery"
         triggeredOn:
           - event: "hardening.delivery.finished"
         tasks: 
         - name: "deployment"
+          properties:
+            deploymentstrategy: "blue_green_service"
         - name: "release"
 ```
 
-### Reserved Keptn Tasks
-
-Keptn supports a set of opinionated tasks for declaring a delivery or remediation sequence: 
-
-* approval
-* deployment
-* evaluation
-* release
-* remediation
-* rollback
-* test
-
-#### Approval
-
-The approval task intercepts the sequence and waits for a required approval (e.g., before deploying an artifact into the next stage). The approval strategy can be defined based on the evaluation result `pass` and `warning`. Keptn supports the following approval strategies for the evaluation results `pass` and `warning`:
-
-  * `automatic`: The artifact is deployed automatically.
-  * `manual`: The user is asked for approval before triggering the deployment.
-
-This allows combinations as follows: 
-
-|                          | Evaluation result: pass           | Evaluation result: warning                 | Behavior  |
-|--------------------------|-----------------------------------|--------------------------------------------|-----------|
-| **Skip approval task:** | pass:automatic | warning:automatic | Regardless of the evaluation result, the approval task is skipped |
-| **Depending on evaluation result:**   | pass:automatic | warning:manual    | If the evaluation result is a **warning**, an approval is required |
-| **Depending on evaluation result:**   | pass:manual    | warning:automatic | If the evaluation result is a **pass**, an approval is required |
-| **Mandatory approval task:**          | pass:manual    | warning:manual    | Regardless of the evaluation result, an approval is required |
-
-Per default, an `automatic` approval strategy is used for evaluation result `pass` and `warning`.
-
-**Usage:**
-
-```
-- name: approval
-  properties: 
-    pass: automatic
-    warning: manual
-```
-
-<details><summary>**Example:** Extended shipyard with a mandatory approval task in production</summary>
-
-<p>
+**Example:** Extended shipyard with two delivery sequence with varying deployment strategies (e.g., `delivery` is used for a Java-service, whereas `delivery-direct` is used for a database):
 
 ```yaml
 apiVersion: spec.keptn.sh/0.2.0
@@ -129,176 +102,20 @@ spec:
     - name: "production"
       sequences:
         - name: "delivery"
-          tasks:
-            - name: "deployment"
-            - name: "approval"
-              properties:
-                pass: "manual"
-                warning: "manual"
-            - name: "release"
-```
-
-</p>
-</details>
-
-#### Deployment
-
-Defines the deployment strategy used to deploy a new version of a service. Keptn supports deployment strategies of type: 
-
-  * `direct`: Deploys a new version of a service by replacing the old version of the service.
-  * `blue_green_service`: Deploys a new version of a service next to the old one. After a successful validation of this new version, it replaces the old one and is marked as stable (i.e., it becomes the `primary`-version).
-
-**Usage:**
-
-```
-- name: deployment
-  properties: 
-    deploymentstrategy: blue_green_service
-```
-
-<details><summary>**Example:** Extended shipyard with direct deployment in dev and blue/green deployment in hardening and production
-</summary>
-
-<p>
-
-```yaml
-apiVersion: spec.keptn.sh/0.2.0
-kind: "Shipyard"
-metadata:
-  name: "shipyard-sockshop"
-spec:
-  stages:
-    - name: "dev"
-      sequences:
-        - name: "delivery"
-          tasks:
-            - name: "deployment"
-              properties:
-                deploymentstrategy: "direct"
-            - name: "evaluation"
-            - name: "release"
-
-    - name: "hardening"
-      sequences:
-        - name: "delivery"
-          triggeredOn:
-            - event: "dev.delivery.finished"
-          tasks:
-            - name: "deployment"
-              properties:
-                deploymentstrategy: "blue_green_service"
-            - name: "evaluation"
-            - name: "release"
-
-    - name: "production"
-      sequences:
-        - name: "delivery"
-          triggeredOn:
-            - event: "staging.delivery.finished"
           tasks:
             - name: "deployment"
               properties:
                 deploymentstrategy: "blue_green_service"
             - name: "release"
-```
-
-</p>
-</details>
 
-#### Evaluation
-
-Defines the quality evaluation that is executed to verify the quality of a deployment based on its SLOs/SLIs.
-
-**Usage:**
-```
-- name: evaluation
-```
-
-#### Release
-
-Defines the releasing task that is executed after a successful deployment happened. This means that production traffic is shifted towards the new deployment in this task. 
-
-**Usage:**
-```
-- name: release
-```
-
-#### Remediation
-
-Defines whether remediation actions are enabled or not.
-
-**Usage:**
-```
-- name: remediation
-```
-
-#### Rollback
-
-Defines the rollback task that is executed when a rollback shall be triggered.
-
-**Usage:**
-```
-- name: rollback
-```
-
-#### Test
-
-Defines the test strategy used to validate a deployment. Keptn supports tests of type:
-
-  * `functional`: Test a deployment based on functional tests.
-  * `performance`: Test a deployment based on performance/load tests.
-
-**Usage:**
-```
-- name: test
-  properties: 
-    teststrategy: functional
-```
-
-<details><summary>**Example:** Extended shipyard with functional tests in dev and performance tests in hardening
-</summary>
-
-<p>
-
-```yaml
-apiVersion: spec.keptn.sh/0.2.0
-kind: "Shipyard"
-metadata:
-  name: "shipyard-sockshop"
-spec:
-  stages:
-    - name: "dev"
-      sequences:
-        - name: "delivery"
+        - name: "delivery-direct"
           tasks:
             - name: "deployment"
               properties:
                 deploymentstrategy: "direct"
-            - name: "test"
-              properties:
-                teststrategy: "functional"
-            - name: "evaluation"
             - name: "release"
+```
 
-    - name: "staging"
-      sequences:
-        - name: "delivery"
-          triggeredOn:
-            - event: "dev.delivery.finished"
-          tasks:
-            - name: "deployment"
-              properties:
-                deploymentstrategy: "blue_green_service"
-            - name: "test"
-              properties:
-                teststrategy: "performance"
-            - name: "evaluation"
-            - name: "release"
-
-``` 
-
-</p>
-</details>
 
 ## Create project with multi-stage delivery