Formatting and add install plan related documentation

content/en/docs/Concepts/crds/installplan.md

@@ -8,3 +8,19 @@ This section is under construction.
 {{% /alert %}}
 
 An InstallPlan defines a set of resources to be created in order to install or upgrade to a specific version of a ClusterService defined by a CSV.
+
+
+InstallPlan can be created in two ways: 
+1. Users can also create an InstallPlan resource directly, containing the names of the desired ClusterServiceVersions and an approval strategy.
+2. When the Catalog Operator find a new InstallPlan, even though it likely created it, it will create an "execution plan" and embed that into the InstallPlan to create all of the required resources. Once approved, whether manually or automatically, the Catalog Operator will implement its portion of the the execution plan, satisfying the underlying expectations of the OLM Operator.
+
+**_Table 1. Install plan phases_**
+
+| Phase              | Description                                                                                 |
+|--------------------|---------------------------------------------------------------------------------------------|
+| None               | initial phase, once seen by the Operator, it is immediately transitioned to `Planning`      |
+| Planning           | dependencies between resources are being resolved, to be stored in the InstallPlan `Status` |
+| RequiresApproval   | occurs when using manual approval, will not transition phase until `approved` field is true |
+| Installing         | resolved resources in the InstallPlan `Status` block are being created                      |
+| Complete           | all resolved resources in the `Status` block exist                                          |
+---------------------

content/en/docs/Tasks/Troubleshooting/clusterserviceversion.md

@@ -11,7 +11,9 @@ description: >
 
 If the OLM operator encounters an unrecoverable error when attempting to install the operator, the `CSV` will be placed in the `failed` phase. The OLM operator will constantly update the `Status` with useful information regarding the state of the `CSV`. You can check the `Status` of your `CSV` with the following command:
 
-`$ kubectl -n my-catalogsource-namespace get csv prometheusoperator.0.32.0 -o yaml | yq r - status`
+```shell script
+$ kubectl -n my-catalogsource-namespace get csv prometheusoperator.0.32.0 -o yaml | yq r - status
+```
 
 >Note: It is possible that the Status is missing, which suggests that the OLM operator is encountering an issue when processing the `CSV` in a very early stage. You should respond by reviewing the logs of the OLM operator.
 

content/en/docs/Tasks/Troubleshooting/install-plan.md

@@ -0,0 +1,49 @@
+---
+title: "InstallPlan"
+linkTitle: "InstallPlan"
+date: 2020-03-25
+weight: 4
+description: >
+  Tips and tricks related to troubleshooting a `InstallPlan`.
+---
+
+
+The primary way an InstallPlan can fail is by not resolving the resources needed to install a CSV.
+
+```yaml
+apiVersion: operators.coreos.com/v1alpha1
+kind: InstallPlan
+metadata:
+  name: olm-testing
+spec:
+  clusterServiceVersionNames:
+  - etcdoperator.v0.7.2
+  approval: Automatic
+```
+
+This installPlan will fail because `etcdoperator.v0.7.2` is not in a catalog. We can see this in its status:
+
+```bash
+$ kubectl get installplans olm-testing -o yaml
+apiVersion: operators.coreos.com/v1alpha1
+kind: InstallPlan
+metadata:
+  ... 
+spec:
+  approval: Automatic
+  clusterServiceVersionNames:
+  - etcdoperator.v0.7.2
+status:
+  catalogSources:
+  - rh-operators
+  conditions:
+  - lastTransitionTime: 2018-01-22T16:05:09Z
+    lastUpdateTime: 2018-01-22T16:06:59Z
+    message: 'not found: ClusterServiceVersion etcdoperator.v0.7.2'
+    reason: DependenciesConflict
+    status: "False"
+    type: Resolved
+  phase: Planning
+```
+
+Error messages like this will displayed for any other inconsistency in the catalog. They can be resolved by either updating the catalog or choosing clusterservices that resolve correctly.

content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md

@@ -2,7 +2,7 @@
 title: "Debugging OLM and Catalog Operator"
 linkTitle: "Debugging OLM/Catalog Operator"
 date: 2020-03-25
-weight: 4
+weight: 5
 description: >
   Tips and tricks related to debugging the OLM or Catalog Operator.
 ---

content/en/docs/Tasks/packaging-an-operator.md

@@ -235,17 +235,12 @@ TODO: example status
 
 ##### Extension apiservers and APIServices
 
-Please see the document on [extension apiservers]() if your operator does not rely on CRDs to provide its API.
+Please see the document on [extension apiservers](https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server/) if your operator does not rely on CRDs to provide its API.
 
 #### Operator SDK
 
-TODO: link to SDK csv generation
+ClusterServiceVersion (CSV) can be generated using operator-sdk. See [Generating a CSV](https://sdk.operatorframework.io/docs/olm-integration/generating-a-csv/) for more details.
 
 #### Advanced and Optional features
 
-Please see the documentation for [advanced operator configuration]() which includes additional suggestions for further integration with OLM.
-
-
-```
-This is the final element on the page and there should be no margin below this.
-```
+Please see the documentation for [advanced operator configuration]() which includes additional suggestions for further integration with OLM.

content/en/docs/Tasks/validate-package.md

@@ -11,15 +11,16 @@ description: >
 
 You can perform some basic static verification on your package by using [`operator-courier`](https://github.com/operator-framework/operator-courier).
 
-```
+```shell script
 $ pip3 install operator-courier
 $ operator-courier verify manifests/my-operator-package
 ```
 
 You can also use `operator-courier` to verify that your operator will be displayed properly on [OperatorHub.io](https://operatorhub.io/).
 
-```
+```shell script
 $ operator-courier verify --ui_validate_io manifests/my-operator-package
+```
 
 
-Note:  Your package can also be validated as part of adding your package to an operator-registry catalog. The operator-registry tools will verify that your operator is packaged properly ("Does it have a valid CSV of the correct format?", "Does my CRD properly reference my CSVs?", etc.).
+>Note: Your package can also be validated   as part of adding your package to an operator-registry catalog. The operator-registry tools will verify that your operator is packaged properly ("Does it have a valid CSV of the correct format?", "Does my CRD properly reference my CSVs?", etc.).

content/en/docs/advanced-tasks/updating-an-operator.md

@@ -12,7 +12,7 @@ If the image used to build the `Catalogsource` uses a versioned tag, update the
 
 For example:
 
-```
+```bash
 $ oc get catsrc operatorhubio-catalog -n olm -o yaml | grep image:
 
     image: quay.io/operator-framework/upstream-community-operators:0.0.1
@@ -25,7 +25,7 @@ If the image used to build the `Catalogsource` uses the `latest` tag, simply del
 
 For example:
 
-```
+```bash
 $ kubectl delete pods -n olm -l olm.catalogSource=operatorhubio-catalog
 
 ```

content/en/docs/contribution-guidelines/local-docs.md

@@ -7,7 +7,7 @@ linkTitle: Local Docs
 
 Clone the repository:
 
-```
+```bash
 $ git clone https://github.com/operator-framework/olm-docs/
 ```
 
@@ -18,16 +18,16 @@ guide](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installatio
 We use `git submodules` to install the docsy theme. From the
 root directory, update the submodules to install the theme.
 
-```
+```bash
 $ git submodule update --init --recursive
 ```
 
 ## Build and Serve
 
 You can build and serve your docs to localhost:1313 with:
 
-```
-hugo server
+```bash
+$ hugo server
 ```
 
 Any changes will be included in real time.