Update documentation

* Update index.adoc
* Add getting started guide
* Document parameters

docs/modules/ROOT/pages/how-tos/getting-started.adoc

@@ -0,0 +1,120 @@
+= Getting started
+
+This guide will help you to get started to use this component to configure cluster-scoped operator subscriptions.
+
+== Prerequisites
+
+* You have an OpenShift 4 cluster on which you want to configure a cluster-scoped operator subscription from a Commodore component
+* You are able to compile the cluster catalog locally
+
+== Steps
+
+[TIP]
+====
+We recommend creating an empty directory and following these steps after changing to that directory.
+
+[source,bash]
+----
+work_dir=$(mktemp -d)
+pushd "${work_dir}"
+----
+====
+
+. Make a note of the cluster and tenant IDs
++
+[source,bash]
+----
+export CLUSTER_ID=c-the-cluster-1234 <1>
+export TENANT_ID=t-the-tenant-1234 <2>
+----
+<1> Replace `c-the-cluster-1234` with the ID of your cluster
+<2> Replace `t-the-tenant-1234` with the ID of your cluster's tenant
+
+. Compile the cluster catalog so you can make changes locally
++
+[source,bash]
+----
+commodore catalog compile "${CLUSTER_ID}"
+----
+
+. Determine whether you want to deploy the operator into namespace `openshift-operators` or `openshift-operators-redhat`.
++
+[source,bash]
+----
+export INSTANCE="openshift-operators" <1>
+----
+<1> Generally, community operators should be deployed in `openshift-operators`, while official RedHat operators should be deployed in `openshift-operators-redhat`.
+If you're not sure, it's best to choose `openshift-operators`.
+
+. Ensure the component is instantiated correctly for the cluster.
++
+[source,bash]
+----
+if [ ! -f "inventory/targets/${INSTANCE}.yml" ]; then
+  yq eval -i ".applications += [\"openshift4-operators as ${INSTANCE}\"]" \
+    "inventory/classes/${TENANT_ID}/${CLUSTER_ID}.yml" <1>
+  (cd "inventory/classes/${TENANT_ID}"; git commit -av; git push origin master) <2>
+fi
+----
+<1> Configure component instance
+<2> Commit and push cluster configuration change
+
+. Now you can create a cluster-scoped operator subscription in your component's Jsonnet code
++
+[source,jsonnet]
+----
+local operatorlib = import 'lib/openshift4-operators.libsonnet';
+
+{
+  subscription: operatorlib.registerSubscription(
+    'openshift-operators', <1>
+    'grafana-operator', <2>
+    'alpha', <3>
+    source='community-operators', <4>
+    installPlanApproval='Automatic', <5>
+    sourceNamespace='openshift-marketplace', <6>
+  )
+}
+----
+<1> The namespace in which the subscription should be created.
+Use the same value as you've selected for `${INSTANCE}` in the 3rd step.
+<2> The name of the subscription
+<3> The update channel for the subscription
+<4> The `CatalogSource` for the subscription.
+For community operators, set this to `community-operators`.
+For RedHat operators, this parameter can be omitted, as it defaults to `redhat-operators`.
+<5> Whether installation and upgrades happen automatically.
+In most cases, you don't have to specify this parameter.
+If the parameter is omitted, it defaults to `Automatic`.
+<6> The namespace in which to look for the `CatalogSource`.
+In most cases, you don't have to specify this parameter.
+If the parameter is omitted, it defaults to `openshift-marketplace`.
+
+. Compile the catalog locally to check your changes
++
+[source,bash]
+----
+commodore catalog compile "${CLUSTER_ID}" --local
+----
++
+You should see the following YAML added to your component's catalog directory
++
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  annotations: {}
+  labels:
+    name: grafana-operator
+  name: grafana-operator
+  namespace: openshift-operators
+spec:
+  channel: alpha
+  installPlanApproval: Automatic
+  name: grafana-operator
+  source: community-operators
+  sourceNamespace: openshift-marketplace
+----
++
+If the component hasn't previously been instantiated for `openshift-operators`, you'll also see new YAML files in the catalog in directory `openshift4-operators`.

docs/modules/ROOT/pages/index.adoc

@@ -1,5 +1,9 @@
 = openshift4-operators
 
-openshift4-operators is a Commodore component to manage openshift4-operators.
+openshift4-operators is a Commodore component to manage target namespaces for cluster-scoped OLM-managed operators on OpenShift 4.
 
-See the xref:references/parameters.adoc[parameters] reference for further details.
+The component provides a Jsonnet library which allows other components to create cluster-scoped operator subscriptions.
+
+See the xref:how-tos/getting-started.adoc[getting started guide] to get started with the component.
+
+See the xref:references/parameters.adoc[parameters] reference for configurable options of the component.

docs/modules/ROOT/pages/references/parameters.adoc

@@ -6,14 +6,8 @@ The parent key for all of the following parameters is `openshift4_operators`.
 
 [horizontal]
 type:: string
-default:: `syn-openshift4-operators`
+default:: `${_instance}`
 
-The namespace in which to deploy this component.
-
-
-== Example
-
-[source,yaml]
-----
-namespace: example-namespace
-----
+The namespace to create for the component instance.
+The component is implemented in such a way that only instances (and therefore namespaces) `openshift-operators` and `openshift-operators-redhat` can be created.
+Generally, it should not be necessary to override this parameter.

docs/modules/ROOT/partials/nav.adoc

@@ -1,2 +1,3 @@
 * xref:index.adoc[Home]
+* xref:how-tos/getting-started.adoc[Getting started]
 * xref:references/parameters.adoc[Parameters]