fix: refresh architecture and philosophy

exdx · exdx · commit c1f91a8dcd43 · 2019-10-28T13:16:56.000-04:00
diff --git a/doc/design/architecture.md b/doc/design/architecture.md
@@ -2,7 +2,7 @@
 
 OLM is composed of two Operators: the OLM Operator and the Catalog Operator.
 
-Each of these Operators are responsible for managing the CRDs that are the basis for the OLM framework:
+Each of these Operators is responsible for managing the CRDs that are the basis for the OLM framework:
 
 | Resource                 | Short Name | Owner   | Description                                                                                |
 |--------------------------|------------|---------|--------------------------------------------------------------------------------------------|
@@ -44,7 +44,7 @@ ClusterServiceVersion:
 
 ## OLM Operator
 
-The OLM Operator is responsible for deploying applications defined by ClusterServiceVersion resources once the required resources specified in the ClusterServiceVersion are present in the cluster.
+The OLM Operator is responsible for installing applications defined by ClusterServiceVersion resources once the required resources specified in the ClusterServiceVersion are present in the cluster.
 The OLM Operator is not concerned with the creation of the required resources; users can choose to manually create these resources using `kubectl` or users can choose to create these resources using the Catalog Operator.
 This separation of concern enables users incremental buy-in in terms of how much of the OLM framework they choose to leverage for their application.
 
@@ -74,15 +74,15 @@ Replacing --> Deleting
 | Pending    | requirements in the CSV are not met, once they are this phase transitions to `Installing`                                                                                                                                             |
 | InstallReady | all requirements in the CSV are present, the Operator will begin executing the install strategy                                                                                                                                     |
 | Installing | the install strategy is being executed and resources are being created, but not all components are reporting as ready                                                                                                                 |
-| Succeeded  | the execution of the Install Strategy was successful; if requirements disappear, or an APIService cert needs to be rotated this may transition back to `Pending`; if an installed component dissapears this may transition to `Failed`|
-| Failed     | upon failed execution of the Install Strategy, or an installed component dissapears the CSV transitions to this phase; if the component can be recreated by OLM, this may transition to `Pending`                                     |
+| Succeeded  | the execution of the Install Strategy was successful; if requirements disappear, or an APIService cert needs to be rotated this may transition back to `Pending`; if an installed component disappears this may transition to `Failed`|
+| Failed     | upon failed execution of the Install Strategy, or an installed component disappears the CSV transitions to this phase; if the component can be recreated by OLM, this may transition to `Pending`                                     |
 | Replacing  | a newer CSV that replaces this one has been discovered in the cluster. This status means the CSV is marked for GC                                                                                                                     |
 | Deleting   | the GC loop has determined this CSV is safe to delete from the cluster. It will disappear soon.                                                                                                                                       |
 > Note: In order to transition, a CSV must first be an active member of an OperatorGroup
 
 ## Catalog Operator
 
-The Catalog Operator is responsible for resolving and installing ClusterServiceVersions and the required resources they specify. It is also responsible for watching catalog sources for updates to packages in channels, and upgrading them (optionally automatically) to the latest available versions.
+The Catalog Operator is responsible for resolving ClusterServiceVersions and the required resources they specify. It is also responsible for watching catalog sources for updates to packages in channels, and upgrading them (optionally automatically) to the latest available versions.
 A user that wishes to track a package in a channel creates a Subscription resource configuring the desired package, channel, and the catalog source from which to pull updates. When updates are found, an appropriate InstallPlan is written into the namespace on behalf of the user.
 Users can also create an InstallPlan resource directly, containing the names of the desired ClusterServiceVersions and an approval strategy and the Catalog Operator will create an execution plan for the creation of all of the required resources.
 Once approved, the Catalog Operator will create all of the resources in an InstallPlan; this should then independently satisfy the OLM Operator, which will proceed to install the ClusterServiceVersions.
diff --git a/doc/design/philosophy.md b/doc/design/philosophy.md
@@ -16,7 +16,7 @@ The goal of the Operator Lifecycle Manager and Cloud Service Catalog is to manag
 
 **Interaction**
 
- * By standardizing the other three, provide a standard way to interact with cloud services and user-defined open cloud services via both the CLI and the Tectonic Console
+ * By standardizing the other three, provide a standard way to interact with cloud services and user-defined open cloud services via both the CLI and the OpenShift web console. 
 
 # Design
 
@@ -82,25 +82,27 @@ OLM defines packaging formats for operators. These are:
 
  * Has metadata about the package (maintainers, icon, etc)
 
- * Declares managed CRDs
+ * Declares owned CRDs
 
-     * These are the CRDs directly managed by the Operator. `EtcdCluster` is managed by the Etcd `ClusterServiceVersion` but not the Vault `ClusterServiceVersion`
+     * These are the CRDs directly owned by the Operator. `EtcdCluster` is owned by the Etcd `ClusterServiceVersion` but not the Vault `ClusterServiceVersion`
 
  * Declares required CRDs
 
      * These are CRDs required by the Operator but not directly managed by it.  `EtcdCluster` is required by the Vault `ClusterServiceVersion` but not managed by it.
 
  * Declares cluster requirements
 
-     * An operator may require a pull secret, a config map, the availability of a cluster feature.
+     * An operator may require a pull secret, a config map, or the availability of a cluster feature.
 
  * Provides an Install Strategy 
 
      * The install strategy tells OLM how to actually create resources in the cluster.
 
-     * Currently the only strategy is "deployment", but planned are: image, helm, and <whatever upstream solutions are created>
+     * Currently the only strategy is `deployment`, which specifies a Kubernetes Deployment
+      
+     * Future install strategies include `image`, `helm`, and upstream community strategies
 
- * Roughly equivalent to dpkg - you can install a dpkg manually, but if you do, dependency resolution is up to you.
+ * Roughly equivalent to dpkg - you can install a dpkg manually, but if you do, dependency resolution is up to you. 
 
 ## InstallPlan
 
@@ -136,7 +138,7 @@ We have two major components that handle the resources described above
 
  **OLM Operator**
 
- * Watches for ClusterServiceVersions in a namespace and checks that requirements are met. If so, runs the service install strategy for the ClusterServiceVersion (e.g: installs deployment)
+ * Watches for ClusterServiceVersions in a namespace and checks that requirements are met. If so, runs the service install strategy for the ClusterServiceVersion and installs the resource into the cluster. For example for a `deployment` strategy installation is achieved by creating a Kubernetes Deployment, which gets resolved by the Deployment controller. 
 
  **Service Catalog Operator**
 
@@ -162,7 +164,7 @@ We have two major components that handle the resources described above
 
 If you don't want to write an operator, the thing you want to package probably fits one of the standard shapes of software that can be deployed on a cluster. You can take advantage of OLM by writing a package that binds your application to one of our standard operators, like [helm-app-operator-kit](https://github.com/coreos/helm-app-operator-kit).
 
-If your use-case doesn't fit one of our standard operators, that means you have domain-specific operational knowledge you need to encode into an operator, and you can take advantage of our Operator SDK for common operator tasks.
+If your use-case doesn't fit one of our standard operators, that means you have domain-specific operational knowledge you need to encode into an operator, and you can take advantage of our [Operator SDK](https://github.com/operator-framework/operator-sdk) for common operator tasks.
 
 **Why are dependencies between operators expressed as a dependency on a CRD?**
 
