Edit Operator docs (#4634)

* Edit Operator docs

* Update docs/install/upgrade/upgrade-installation-with-operator.md

Co-authored-by: Peter Mbanugo <p.mbanugo@yahoo.com>

* fix typo

Co-authored-by: Peter Mbanugo <p.mbanugo@yahoo.com>

config/nav.yml

@@ -40,10 +40,10 @@ nav:
         - Knative Eventing installation files: install/eventing/eventing-installation-files.md
       # Operator Installation
       - Install with Knative Operator:
-        - Installing with the Operator: install/operator/knative-with-operators.md
-        - Configuring Knative by using the Operator: install/operator/configuring-with-operator.md
-        - Configuring Knative Eventing CRDs: install/operator/configuring-eventing-cr.md
+        - Installing using the Operator: install/operator/knative-with-operators.md
+        - Configuring Knative using the Operator: install/operator/configuring-with-operator.md
         - Configuring Knative Serving CRDs: install/operator/configuring-serving-cr.md
+        - Configuring Knative Eventing CRDs: install/operator/configuring-eventing-cr.md
       # kn Installation
       - Install the Knative CLI:
         - CLI tools overview: install/client/README.md

docs/install/upgrade/upgrade-installation-with-operator.md

@@ -15,7 +15,7 @@ The Knative Operator supports up to the last three major releases. For example,
 
 To upgrade, apply the Operator custom resources, adding the `spec.version` for the Knative version that you want to upgrade to:
 
-1. Copy the following YAML into a file:
+1. Create a YAML file containing the following:
 
     ```yaml
     apiVersion: operator.knative.dev/v1alpha1
@@ -24,8 +24,9 @@ To upgrade, apply the Operator custom resources, adding the `spec.version` for t
       name: knative-serving
       namespace: knative-serving
     spec:
-      version: "0.23"
+      version: "<new-version>"
     ```
+    Where `<new-version>` is the Knative version that you want to upgrade to.
 
 1. Apply the YAML file by running the command:
 
@@ -122,7 +123,9 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v
 
 === "Knative Serving"
 
-1. Copy the following YAML into a file:
+To rollback to a previous version of Knative Serving:
+
+1. Create a YAML file containing the following:
 
     ```yaml
     apiVersion: operator.knative.dev/v1alpha1
@@ -131,8 +134,9 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v
       name: knative-serving
       namespace: knative-serving
     spec:
-      version: "0.22"
+      version: "<previous-version>"
     ```
+    Where `<previous-version>` is the Knative version that you want to downgrade to.
 
 1. Apply the YAML file by running the command:
 
@@ -143,7 +147,9 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v
 
 === "Knative Eventing"
 
-1. Copy the following YAML into a file:
+To rollback to a previous version of Knative Eventing:
+
+1. Create a YAML file containing the following:
 
     ```yaml
     apiVersion: operator.knative.dev/v1alpha1
@@ -152,8 +158,10 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v
       name: knative-eventing
       namespace: knative-eventing
     spec:
-      version: "0.22"
+      version: "<previous-version>"
     ```
+    Where `<previous-version>` is the Knative version that you want to downgrade to.
+
 1. Apply the YAML file by running the command:
 
     ```bash

docs/snippets/dns.md

@@ -1,4 +1,4 @@
-## Configure DNS
+### Configure DNS
 
 You can configure DNS to prevent the need to run curl commands with a host header.
 

docs/snippets/real-dns-operator.md

@@ -7,30 +7,32 @@
     - If the networking layer produced an External IP address, then configure a
       wildcard `A` record for the domain:
 
-      ```
-      # Here knative.example.com is the domain suffix for your cluster
-      *.knative.example.com == A 35.233.41.212
-      ```
+        ```
+        # Here knative.example.com is the domain suffix for your cluster
+        *.knative.example.com == A 35.233.41.212
+        ```
 
     - If the networking layer produced a CNAME, then configure a CNAME record for the domain:
 
-      ```
-      # Here knative.example.com is the domain suffix for your cluster
-      *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com
-      ```
+        ```
+        # Here knative.example.com is the domain suffix for your cluster
+        *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com
+        ```
 
-    - Once your DNS provider has been configured, add the following section into your existing Serving CR, and apply it:
+    - Once your DNS provider has been configured, add `spec.config.domain` into
+    your existing Serving CR, and apply it:
 
-      ```yaml
-      # Replace knative.example.com with your domain suffix
-      apiVersion: operator.knative.dev/v1alpha1
-      kind: KnativeServing
-      metadata:
-        name: knative-serving
-        namespace: knative-serving
-      spec:
-        config:
-          domain:
-            "knative.example.com": ""
-        ...
-      ```
+        ```yaml
+        # Replace knative.example.com with your domain suffix
+        apiVersion: operator.knative.dev/v1alpha1
+        kind: KnativeServing
+        metadata:
+          name: knative-serving
+          namespace: knative-serving
+        spec:
+          ...
+          config:
+            domain:
+              "knative.example.com": ""
+          ...
+        ```

docs/snippets/real-dns-yaml.md

@@ -7,24 +7,24 @@
     - If the networking layer produced an External IP address, then configure a
       wildcard `A` record for the domain:
 
-      ```
-      # Here knative.example.com is the domain suffix for your cluster
-      *.knative.example.com == A 35.233.41.212
-      ```
+        ```
+        # Here knative.example.com is the domain suffix for your cluster
+        *.knative.example.com == A 35.233.41.212
+        ```
 
     - If the networking layer produced a CNAME, then configure a CNAME record for the domain:
 
-      ```
-      # Here knative.example.com is the domain suffix for your cluster
-      *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com
-      ```
+        ```
+        # Here knative.example.com is the domain suffix for your cluster
+        *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com
+        ```
 
     - Once your DNS provider has been configured, direct Knative to use that domain:
 
-      ```yaml
-      # Replace knative.example.com with your domain suffix
-      kubectl patch configmap/config-domain \
-        --namespace knative-serving \
-        --type merge \
-        --patch '{"data":{"knative.example.com":""}}'
-      ```
+        ```yaml
+        # Replace knative.example.com with your domain suffix
+        kubectl patch configmap/config-domain \
+          --namespace knative-serving \
+          --type merge \
+          --patch '{"data":{"knative.example.com":""}}'
+        ```