Docs: add new troublshooting page + fix markdown format

README.md

@@ -11,6 +11,7 @@ The latest version of operator can be installed from the `community-operators` c
 and installed from source manually, see the Developer guide for further instructions.
 
 1. Subscribe to operator by creating following subscription
+
     ```console
     cat <<EOF | oc create -f -
     apiVersion: operators.coreos.com/v1alpha1
@@ -33,7 +34,6 @@ and installed from source manually, see the Developer guide for further instruct
 Developer Preview of the new Open Data Hub operator codebase is now avaible.
 Refer [Dev-Preview.md](./docs/Dev-Preview.md) for testing preview features.
 
-
 ### Developer Guide
 
 #### Pre-requisites
@@ -117,12 +117,13 @@ There are 2 ways to test your changes with modification:
     by using this method, it overwrites manifests and component images if images are set in the params.env file
 2. [Under implementation] build operator image with local manifests   
 
-### Example DataScienceCluster 
+### Example DataScienceCluster
 
 When the operator is installed successfully in the cluster, a user can create a `DataScienceCluster` CR to enable ODH 
 components. At a given time, ODH supports only **one** instance of the CR, which can be updated to get custom list of components.
 
 1. Enable all components
+
     ```console
       apiVersion: datasciencecluster.opendatahub.io/v1
       kind: DataScienceCluster
@@ -145,6 +146,7 @@ components. At a given time, ODH supports only **one** instance of the CR, which
           workbenches:
             managementState: Managed
     ```
+
 2. Enable only Dashboard and Workbenches
 
     ```console
@@ -162,7 +164,6 @@ components. At a given time, ODH supports only **one** instance of the CR, which
 
 **Note:** Default value for a component is `false`.
 
-
 ### Run e2e Tests
 
 A user can run the e2e tests in the same namespace as the operator. To deploy
@@ -187,11 +188,13 @@ variable. Following table lists all the available flags to run the tests:
 |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
 | --skip-deletion | To skip running  of `dsc-deletion` test that includes deleting `DataScienceCluster` resources. Assign this variable to `true` to skip DataScienceCluster deletion. | false         |
 
-
-
 Example command to run full test suite skipping the test
 for DataScienceCluster deletion.
 
 ```shell
 make e2e-test -e OPERATOR_NAMESPACE=<namespace> -e E2E_TEST_FLAGS="--skip-deletion=true"
-```
+```
+
+### Troubleshooting
+
+Please refer to [troubleshooting documentation](docs/troubleshooting.md)

docs/DESIGN.md

@@ -3,6 +3,7 @@
 ## Motivation
 
 Following are the general goals for redesigning the existing ODH operator:
+
 - Create an opinionated deployment of ODH components.
 - Provide users / cluster administrators with ability to customize components
 - Provide ability to enable / disable individual components
@@ -13,7 +14,8 @@ Following are the general goals for redesigning the existing ODH operator:
 
 ## Proposed Design
 
-To deploy ODH components seamlessly, ODH operator will watch two CRDS:
+To deploy ODH components seamlessly, ODH operator will watch two CRDs:
+
 - DSCInitialization
 - DataScienceCluster
 
@@ -25,7 +27,6 @@ To deploy ODH components seamlessly, ODH operator will watch two CRDS:
 - Some examples of initial setup include creating namespaces, network policies, SCCs, common configmaps and secrets.
 - This will be a singleton CR i.e 1 instance of this CR will always be present in the cluster.
 - DSCInitialization CR can be deleted to re-run initial setup without requiring re-build of the operator.
-- **This CR is not configurable for end users**
 
 ### DataScienceCluster
 
@@ -36,8 +37,8 @@ To deploy ODH components seamlessly, ODH operator will watch two CRDS:
 
 ## Examples
 
-
 1. Enable all components
+
     ```console
       apiVersion: datasciencecluster.opendatahub.io/v1
       kind: DataScienceCluster
@@ -60,6 +61,7 @@ To deploy ODH components seamlessly, ODH operator will watch two CRDS:
           workbenches:
             managementState: Managed
     ```
+
 2. Enable only Dashboard and Workbenches(Jupyter Notebooks)
 
     ```console
@@ -75,7 +77,7 @@ To deploy ODH components seamlessly, ODH operator will watch two CRDS:
             managementState: Managed 
     ```
 
-3. Enable Data Science Pipelines 
+3. Enable Data Science Pipelines
 
     ```console
       apiVersion: datasciencecluster.opendatahub.io/v1
@@ -86,4 +88,4 @@ To deploy ODH components seamlessly, ODH operator will watch two CRDS:
         components:
           datasciencepipelines:
             managementState: Managed
-    ```
+    ```

docs/Dev-Preview.md

@@ -75,7 +75,7 @@ EOF
 
 1. When Operator is installed it creates a namespace called `opendatahub`.
 2. Users need to create required `DataScienceCluster` resource by going to the `Installed Operators` tab in the OpenShift Cluster.
-3. Users should explicitly set components with `enabled: true` in order for components to be installed.
+3. Users should explicitly set components with `managementState: Managed` in order for components to be installed.
 
 ```console
 cat <<EOF | oc apply -f -
@@ -102,8 +102,7 @@ spec:
 EOF
 ```
 
-
 ### Integrated Components
 
-- Currently on integration of ODH [core](https://opendatahub.io/docs/tiered-components/) components is available with the Operator. 
+- Currently on integration of ODH [core components](https://opendatahub.io/docs/tiered-components/) are available with the Operator.
 - Tier 1 and Tier 2 components can be deployed manually using [kustomize build](https://kubectl.docs.kubernetes.io/references/kustomize/cmd/build/)

docs/troubleshooting.md

@@ -0,0 +1,19 @@
+# What
+
+This document serves as the knowledge base for troubleshooting the Open Data Hub Operator.
+
+## Troubleshooting
+
+### Upgrade from Operator v2.0/v2.1 to v2.2+
+
+This also applies to any local build deployment from the "main" branch.
+
+To upgrade, follow these steps:
+
+- Disable the component(s) in your DSC instance.
+- Delete both the DSC instance and DSCI instance.
+- Click "uninstall" Open Data Hub operator.
+- If exposed on v1alpha1, delete the DSC CRD and DSCI CRD.
+
+All of the above steps can be performed either through the console UI or via the `oc`/`kubectl` CLI.
+After completing these steps, please refer to the installation guide to proceed with a clean installation of the v2.2+ operator.