Add core tasks and troubleshooting docs

Docs related to basic use cases and troubleshooting those
use cases.

Author: anik120

content/en/docs/Concepts/_index.md

@@ -3,15 +3,103 @@ title: "Concepts"
 linkTitle: "Concepts"
 weight: 4
 description: >
-  What does your user need to understand about your project in order to use it - or potentially contribute to it? 
+  This page contains a list of terms defined by OLM, along with their definitions and common Aliases. 
 ---
 
-{{% pageinfo %}}
-This is a placeholder page that shows you how to use this template site.
-{{% /pageinfo %}}
+{{% alert title="Warning" color="warning" %}}
+These pages are under construction. Please continue to use the [docs in
+OLM git book](https://github.com/operator-framework/olm-book)
+for now.
+{{% /alert %}}
 
-For many projects, users may not need much information beyond the information in the [Overview](/docs/overview/), so this section is **optional**. However if there are areas where your users will need a more detailed understanding of a given term or feature in order to do anything useful with your project (or to not make mistakes when using it) put that information in this section. For example, you may want to add some conceptual pages if you have a large project with many components and a complex architecture.
 
-Remember to focus on what the user needs to know, not just what you think is interesting about your project! If they don’t need to understand your original design decisions to use or contribute to the project, don’t put them in, or include your design docs in your repo and link to them. Similarly, most users will probably need to know more about how features work when in use rather than how they are implemented. Consider a separate architecture page for more detailed implementation and system design information that potential project contributors can consult.
+## CustomResourceDefinitions (CRDs)
+
+The following [CustomResourceDefinitions](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) are defined by the OLM.
+
+### ClusterServiceVersion
+
+**Definition**: The ClusterServiceVersion represents a particular version of a ClusterService and its operator. It includes metadata such as name, description, version, repository link, labels, icon, etc. It declares `owned`/`required` CRDs, cluster requirements, and install strategy that tells OLM how to create required resources and set up the operator as a [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/).
+
+**Aliases**: CSV(s)
+
+### CatalogSources
+
+**Definition**: The CatalogSource represents a repository of bundles, which are collections of resources that must contain [CSVs](#ClusterServiceVersion), [CRDs](#CustomResourceDefinitions), and package definitions. There are multiple implementations of a CatalogSource backend, the current recommendation is to use a [registry image](#Index).
+
+**Aliases**: CatSrc(s)
+
+### InstallPlans
+
+**Definition**: The 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.
+
+**Aliases**: IP(s)
+
+### OperatorGroups
+
+**Definition**: The OperatorGroup selects a set of target namespaces in which to generate required RBAC access for its member Operators.
+
+**Aliases**: OG(s)
+
+### OperatorSources
+
+**Definition**: The OperatorSources are a way of pointing to external app registry namespaces that contain a catalog of operators. Applying an OperatorSource to a cluster makes the operators in that OperatorSource available for installation in that cluster.
+
+**Aliases**: OpSrc(s)
+
+### Subscriptions
+
+**Definition**: Subscriptions are Custom Resources that relate an operator to a CatalogSource. Subscriptions describe which channel of an operator package to subscribe to, and whether to perform updates automatically or manually. If set to automatic, the Subscription ensures OLM will manage and upgrade the operator to ensure the latest version is always running in the cluster.
+
+**Aliases**: Subs(s)
+
+## OLM Concepts
+
+### Bundle
+
+**Definition**: A collection of Operator [CSV](#ClusterServiceVersion), manifests, and metadata which together form a unique version of an Operator that can be installed onto the cluster. 
+
+### Bundle Image
+
+**Definition**: An image of a bundle is built from operator manifests and contains exactly one [bundle](#Bundle). The bundle images are stored and distributed by OCI spec container registries such as Quay.io or DockerHub.
+
+### Channel
+
+**Definition**: The channel defines a stream of updates for an operator and is used to roll out updates for subscribers. The head points at the latest version of that channel. For example, a stable channel would have all stable versions of an operator arranged from the earliest to the latest. An operator can have several channels, and a subscription binding to a certain channel would only look for updates in that channel.
+
+### Channel Head
+
+**Definition**: Head refers to the latest known update in a particular [channel](#Channel).
+
+### Catalog Image
+
+**Definition**: A catalog image is a containerized datastore that describes a set of operator and update metadata that can be installed onto a cluster via OLM.
+
+**Aliases**: OPM Index
+
+### Dependency
+
+**Definition**: An Operator may have a dependency on another Operator being present in the cluster. For example, the Vault Operator has a dependency on the Etcd Operator for its data persistence layer. OLM resolves these dependencies by ensuring all specified versions of Operators and CRDs are installed on the cluster during the installation phase. This dependency is resolved by finding and installing an Operator in a Catalog that satisfies the required CRD API, and not related to [packages](#Packages)/[bundles](#Bundles).
+
+**Aliases**: Operator Dependency, GVK Dependency, API Dependency, Required CRD
+
+### Index
+
+**Definition**: The Index refers to an image of a database (a database snapshot) that contains information about Operator bundles including CSVs, CRDs, etc of all versions. This index can host a history of used operators on a cluster and be maintained by adding or removing operators.
+
+**Aliases**: Registry DB, Catalog DB, OPM registry
+
+### Package
+
+**Definition**: A package is a directory that encloses all released history of an Operator with each version contained
+ in the bundle format. A released version of an Operator is described in a ClusterServiceVersion manifest alongside the CustomResourceDefinitions.
+
+### Registry
+
+**Definition**: A database which stores [Bundle Images](#Bundle-Image) of Operators, each with all of its latest/historical versions in all [channels](#Channel).
+
+### Upgrade Graph
+
+**Definition**: An upgrade graph links versions of [CSV](#ClusterServiceVersions) together, similar to the upgrade graph of any other packaged software. Operators can be installed sequentially, or certain versions can be skipped. The update graph is expected to grow only at the head with newer versions being added. This is automatically resolved as part 
 
 

content/en/docs/Getting started/_index.md

@@ -3,21 +3,21 @@ title: "Getting Started"
 linkTitle: "Getting Started"
 weight: 2
 description: >
-  What does your user need to know to try your project?
+  Install OLM in a kubernetes cluster.
 ---
 
 ## Prerequisites
 
-- [git][git_tool]
-- [go][go_tool] version v1.12+.
-- [docker][docker_tool] version 17.03+.
-  - Alternatively [podman][podman_tool] `v1.2.0+` or [buildah][buildah_tool] `v1.7+`
-- [kubectl][kubectl_tool] version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
+- [git](https://git-scm.com/downloads)
+- [go](https://golang.org/dl/) version `v1.12+`.
+- [docker](https://docs.docker.com/install/) version `17.03`+.
+  - Alternatively [podman](https://github.com/containers/libpod/blob/master/install.md) `v1.2.0+` or [buildah](https://github.com/containers/buildah/blob/master/install.md) `v1.7+`
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) `v1.11.3+`.
+- Access to a Kubernetes `v1.11.3+` cluster.
 
 ## Installation
 
-## Install Released OLM
+### Install Released OLM
 For installing release versions of OLM, for example version 0.12.0, you can use the following command:
 
 ```bash
@@ -28,25 +28,18 @@ kubectl apply -f https://github.com/operator-framework/operator-lifecycle-manage
 
 Learn more about available releases [here](https://github.com/operator-framework/operator-lifecycle-manager/releases).
 
-## Install From Git Repository Master Branch
 
-You can install OLM from the master branch of the [operator-framework/operator-lifecycle-manager](https://github.com/operator-framework/operator-lifecycle-manager/) repository with the following: 
-
-```bash
-kubectl create -f https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/quickstart/crds.yaml
-kubectl create -f https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/quickstart/olm.yaml
-```
-You can also clone the entire git repository and use the [Makefile](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Makefile) for deploying OLM locally on [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) for development purposes.
+To deploy OLM locally on a [minikube cluster](https://kubernetes.io/docs/tasks/tools/install-minikube/) for development work, use the `run-local` target in the [Makefile](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Makefile).
 
 ```bash
 git clone https://github.com/operator-framework/operator-lifecycle-manager.git
 cd operator-lifecycle-manager
 make run-local
 ```
 
-## Verify OLM Install
+## Try it out!
 
-You can verify the necessary CustomResourceDefinitions are created from applying the `crds.yaml` file with the following:
+You can verify your installation of OLM by first checking for all the neccesasary CRDs in the cluster:
 
 ```bash
 $ kubectl get crd
@@ -57,7 +50,8 @@ installplans.operators.coreos.com             2019-10-21T18:15:27Z
 operatorgroups.operators.coreos.com           2019-10-21T18:15:27Z
 subscriptions.operators.coreos.com            2019-10-21T18:15:27Z
 ```
-You can also visualize OLM deployments from applying `olm.yaml` file with the following:
+
+And then inspecting the deployments of OLM and it's related componenents:
 
 ```bash
 $ kubectl get deploy -n olm
@@ -67,10 +61,3 @@ olm-operator       1/1     1            1           5m52s
 packageserver      2/2     2            2           5m43s
 ```
 
-## Setup
-
-Is there any initial setup users need to do after installation to try your project?
-
-## Try it out!
-
-Can your users test their installation, for example by running a commmand or deploying a Hello World example?

content/en/docs/Tasks/porridge.md renamed to content/en/docs/Getting started/example-page.md

@@ -1,7 +1,7 @@
 ---
-title: "Porridge Assessment"
+title: "Example Page"
+linkTitle: "Example Page"
 date: 2017-01-05
-weight: 4
 description: >
   A short lead descripton about this content page. It can be **bold** or _italic_ and can be split over multiple paragraphs.
 ---

content/en/docs/Overview/_index.md

@@ -3,18 +3,16 @@ title: "Overview"
 linkTitle: "Overview"
 weight: 1
 description: >
-    This page introduces you to OLM and why we use it
+    This page introduces you to OLM and what you can achieve with it
 ---
 
-## What is it?
+## What is OLM?
 
-Operator Lifecycle Manager (OLM) helps users install, update, and manage the lifecycle of all Operators and their associated services running across their clusters. It is part of the Operator Framework, an open source toolkit designed to manage Kubernetes native applications (Operators) in an effective, automated, and scalable way.
+[Operator Lifecycle Manager (OLM)](https://github.com/operator-framework/operator-lifecycle-manager) is a component of the [Operator Framework](https://github.com/operator-framework), an open source toolkit to manage Kubernetes native applications, called Operators, in an effective, automated, and scalable way. OLM extends Kubernetes to provide a declarative way to install, manage, and upgrade Operators and their dependencies in a cluster.
 
-The OLM runs by default in OpenShift Container Platform 4.3, which aids cluster administrators in installing, upgrading, and granting access to Operators running on their cluster. The OpenShift Container Platform web console provides management screens for cluster administrators to install Operators, as well as grant specific projects access to use the catalog of Operators available on the cluster.
+Read more in the [introduction blog post](https://operatorhub.io/what-is-an-operator).
 
-For developers, a self-service experience allows provisioning and configuring instances of databases, monitoring, and big data services without having to be subject matter experts, because the Operator has that knowledge baked into it.
-
-## Why would i use OLM? 
+## Why do I want OLM?
 
 ### Over-the-Air Updates and Catalogs
 Kubernetes clusters are being kept up to date using elaborate update mechanisms today, more often automatically and in the background. Operators, being cluster extensions, should follow that. OLM has a concept of catalogs from which Operators are available to install and being kept up to date. In this model OLM allows maintainers granular authoring of the update path and gives commercial vendors a flexible publishing mechanism using channels.
@@ -29,22 +27,23 @@ OLM advertises installed Operators and their services into the namespaces of ten
 Operators must claim ownership of their APIs. OLM will prevent conflicting Operators owning the same APIs being installed, ensuring cluster stability.
 
 ### Declarative UI controls
-Operators can behave like managed service providers. Their user interface on the command line are APIs. For graphical consoles OLM annotates those APIs with descriptors that drive the creation of rich interfaces and forms for users to interact with the Operator in a natural, cloud-like way.
-
-## Why do I want it?
+Operators can behave like managed service providers. Their user interface on the command line are APIs. For graphical consoles OLM annotates those APIs with descriptors that drive the creation of rich interfaces and forms for users to interact with the Operator in a natural, cloud-like way. 
 
-Help your user know if your project will help them. Useful information can include: 
+## What is it good for?
+ 
+What types of problems does your project solve? What are the benefits of using it?
 
-* **What is it good for?**: What types of problems does your project solve? What are the benefits of using it?
+## What is it not good for?
+ 
+For example, point out situations that might intuitively seem suited for your project, but aren't for some reason. Also mention known limitations, scaling issues, or anything else that might let your users know if the project is not for them.
 
-* **What is it not good for?**: For example, point out situations that might intuitively seem suited for your project, but aren't for some reason. Also mention known limitations, scaling issues, or anything else that might let your users know if the project is not for them.
+## What is it *not yet* good for?
 
-* **What is it *not yet* good for?**: Highlight any useful features that are coming soon.
+Highlight any useful features that are coming soon.
 
 ## Where should I go next?
 
 Give your users next steps from the Overview. For example:
 
-* [Getting Started](/Installation/): Get started with $project
-* [Examples](/examples/): Check out some example code!
-
+* [Getting Started](/docs/getting-started/): Get started with $project
+* [Examples](/docs/examples/): Check out some example code!