updates from review comments

Author: kalexand-rh

modules/abstraction-layers.adoc

@@ -5,7 +5,7 @@
 [id='abstraction-layers-{context}']
 = {product-title} abstraction layers
 
-The Docker service provides the abstraction for packaging and creating
+The container service provides the abstraction for packaging and creating
 Linux-based, lightweight container images. Kubernetes provides the
 cluster management and orchestrates containers on multiple hosts.
 

modules/architecture-overview.adoc

@@ -17,7 +17,7 @@ and managing utilities that your apps use.
 {product-title} v4 runs on top of a Kubernetes cluster, with data about the
 objects stored in etcd, a reliable clustered key-value store. The cluster is 
 enhanced with standard components that you need to run your cluster, including 
-network, ingress, logging and monitoring, that run as Operators to increase the
+network, ingress, logging, and monitoring, that run as Operators to increase the
 ease and automation of installation, scaling, and maintenance.
 
 ////

modules/cloud_installations.adoc

@@ -21,13 +21,13 @@ such as ...
 
 When you install a fully-managed {product-title} cluster, you download the
 installer from link:try.openshift.com. This site manages:
-* Rest API for accounts
+* REST API for accounts
 * Registry tokens, which are the pull secrets that you use to obtain the required
 components
 * Cluster registration, which associates the cluster identity to your Red Hat
-account to facilitate usage metrics gathering
+account to facilitate the gathering of usage metrics
 
-In {product-title} version 4.0, the installer is a go binary that performs a
+In {product-title} version 4.0, the installer is a Go binary that performs a
 series of file transformations on a set of assets. With the fully-managed option,
 you delegate the infrastructure bootstrapping and provisioning to the installer
 instead of doing it yourself. Because you do not use the installer to upgrade or

modules/installation-options.adoc

@@ -23,7 +23,7 @@ With the bring your own infrastructure option, you have more responsibilities.
 You must provide the hosts and update RHEL on them. {product-title} provides:
 
 * Managed control plane
-* Ansible to manage kubelet and runtime
+* Ansible to manage kubelet and container runtime
 
 
 With both installation types, installation and upgrade both use an Operator

modules/machine-api-overview.adoc

@@ -16,7 +16,7 @@ custom {product-title} resources.
 
 The three primary resources are:
 
-`Machines`:: A fundamental unit that describes a node host. A `machine` has a
+`Machines`:: A fundamental unit that describes a `Node`. A `machine` has a
 class, which describes the types of compute nodes that are offered for different
 cloud platforms. For example, a `machine` type for a worker node on Amazon Web
 Services (AWS) might define a specific machine type and required metadata.
@@ -33,6 +33,9 @@ The following custom resources add more capabilities to your cluster:
 `MachineAutoscaler`:: This resource automatically scales `machines` in
 a cloud. You can set the minimum and maximum scaling boundaries for nodes in a
 specified `MachineSet`, and the `MachineAutoscaler` maintains that range of nodes.
+The `MachineAutoscaler` object takes effect after a `ClusterAutoscaler` object
+exists. Both `ClusterAutoscaler` and `MachineAutoscaler` resources are made
+available by the `ClusterAutoscalerOperator`.
 `MachineHealthChecker`:: This resource detects when a machine is unhealthy,
 deletes it, and, on supported platforms, makes a new machine.
 `ClusterAutoscaler`:: This resource is based on the upstream
@@ -48,9 +51,9 @@ new nodes are not brought online for less important pods. You can also set the
 ScalingPolicy so you can scale up nodes but not scale them down.
 
 
-In 3.x, you couldn't roll out a multi-az architecture easily because the cluster
-did not manage machine provisioning. It's easier in 4.0. Each machinset is scoped
-to a single az so the installer will actually send out machinesets across AZs
-on your behalf. And then because your compute is actually dynamic here, and in 
+In {product-title} version 3.11, you could not roll out a multi-zone architecture easily because the cluster
+did not manage machine provisioning. It is easier in 4.0. Each `MachineSet` is scoped
+to a single zone, so the installer sends out `MachineSets` across availability zones
+on your behalf. And then because your compute is dynamic, and in 
 the face of a zone failure, you always have a zone for when you need to rebalance
-your machines. the autoscaler proviedes best-effort balancing over the life of a cluster.
+your machines. The autoscaler provides best-effort balancing over the life of a cluster.

modules/node-management.adoc

@@ -8,7 +8,7 @@
 The fully-managed version of {product-title} version 4.0 integrates management of
 the container operating system and cluster management. Because the cluster manages
 both its updates and updates to RHCOS, {product-title} provides an opinionated
-lifecycle management experience that simplifies the orchestration of node upgrades.
+lifecycle management experience that simplifies the orchestration of upgrades.
 
 {product-title} employs three DaemonSets and controllers to simplify node management:
 
@@ -22,7 +22,7 @@ the hosts by using standard Kuberentes-style constructs. A `machine-config-daemo
 DaemonSet runs on each compute node in the cluster and watches for changes in
 the machine configuration for it to apply. The machine configuration is a subset
 of the Ignition configuration. The `machine-config-daemon` reads the machine configuration to see
-if it needs to do an `os tree` update, if it should apply a series of `systemd`
+if it needs to do an OSTree update, if it should apply a series of systemd
 kubelet file changes, configuration changes, or other changes to the
 operating system or {product-title} configuration.
 
@@ -33,14 +33,16 @@ directs a node to update. The node sees that it needs to change, drains off its
 pods, applies the update, and reboots. This process is key to the success of
 managing {product-title} and RHCOS updates together.
 
-The `machine-config-server` applies configurations to nodes as they join the
+The `machine-config-server` provides configurations to nodes as they join the
 cluster. It orchestrates configuration to nodes and changes to the operating system
 and is used in both cluster installation and node maintenance. The
 `machine-config-server` components upgrade the operating system and controls the Ignition
 configuration for nodes.
 
+////
 The `bootkube` process calls the `machine-config-server` component when the 
 {product-title} installer bootstraps the initial master node. After installation,
 the `machine-config-server` runs in the cluster.  It reads the `machine-config`
 custom resource definitions (CRDs) and serves the required Ignition configurations
 to new nodes when they join the cluster.
+////

modules/node-types.adoc

@@ -5,7 +5,7 @@
 [id='node-roles-{context}']
 = Node roles in {product-title}
 
-{product-title} assigns nodes different roles. These roles define the function
+{product-title} assigns hosts different roles. These roles define the function
 of the node within the cluster. The cluster contains standard definitions for
 standard role types, such as bootstrap, master, and worker. 
 

modules/operators-overview.adoc

@@ -26,7 +26,7 @@ global configuration file.
 
 In {product-title} v4, all control plane components are run and managed as
 applications on the infrastructure to ensure a uniform and consistent management
-experience. The control plane, services run as static pods so they can
+experience. The control plane services run as static pods so they can
 manage normal workloads or processes the same way that they manage disaster
 recovery. Aside from the core control plane components, other services run as 
 normal pods on the cluster, managed by regular Kubernetes constructs. Unlike in the past
@@ -40,26 +40,28 @@ always runs as a `systemd` process.
 The cluster version Operator, when we talk about payload manifests, is a
 second-level Operator, the Operators that actually manage {product-title} as if
 it were a native Kubernetes application. Second-level Operators are not a
-codified concept, but thenamespace where your code exists, the service accounts
-or roles the second-level Operator runs as, the CRD and pull secret that drives
-the operation of the Operator, and the Operator deployment.
+codified concept, but the namespace where your code exists, the service accounts
+or roles the second-level Operator runs as, the
+link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions[Custom Resource Definition] (CRD)
+and pull secret that drives the operation of the Operator, and the Operator deployment.
 
-Second-level Operators write out to a CRD resource called the cluster Operator
+Second-level Operators write out to a CRD resource called the ClusterOperator
 that allows the cluster version Operator to understand the progress of the
-managed component's deployment
+managed component's deployment.
 
 [id='OLM-operators-{context}']
 == Operators managed by OLM
 
-In addition to the Operators that comprise {product-title}, the Cluster
-Operator Lifecycle Management (OLM) component manages more Operators.
+The Cluster Operator Lifecycle Management (OLM) component manages Operators
+that are available for use in applications. It does not manage the Operators that
+comprise {product-title}.
 OLM is a framework that manages Kubernetes-native applications as Operators.
 Instead of managing Kubernetes manifests, it manages Kubernetes Operators.
 OLM manages two classes of Operators, Red Hat Operators and certified Operators.
 
 Some Red Hat Operators drive the cluster functions, like the scheduler and
-problem detectors. Others are provider for you to manage yourself and use in
+problem detectors. Others are provided for you to manage yourself and use in
 your applications, like etcd. {product-title} also offers certified Operators,
-which the community built around the OLM and maintains. These certified Operators
-are traditional applications that are Kubernetes-aware because they are wrapped
-in an Operator.
+which the community built and maintains. These certified Operators provide an
+API layer to traditional applications so you can manage the application through
+Kubernetes constructs.

modules/update-service-overview.adoc

@@ -8,8 +8,9 @@
 The {product-title} update service is the hosted service that provides over the air updates to both 
 {product-title} and RHCOS. It provides a graph, or diagram that contain
 _vertices_ and the _edges_ that connect them, of component Operators. The edges
-in the graph show which versions you can safely upgrade to. The cluster version
-Operator checks with the {product-title} update service and determines valid upgrades and upgrade paths
+in the graph show which versions you can safely upgrade to, and the vertices
+vertices are update payloads that specify the intended state of the managed cluster components.
+The cluster versionOperator checks with the {product-title} update service and determines valid upgrades and upgrade paths
 based on current component versions and information in the graph. If you
 configure it to do so, the {product-title} update service sends the release artifacts that it needs to
 perform the upgrade to your image registry, and the cluster version Operator
@@ -23,16 +24,18 @@ as other component packages. After the pipeline confirms the suitability of a
 release, the {product-title} update service can apply the update to your cluster or notify you that it
 is available.
 
+////
 The interaction between the registry and the {product-title} update service is different during
 bootstrap and continuous update modes. When you bootstrap the initial
 infrastructure, the cluster version Operator finds 
 the fully qualified image name for the shortname of the images that it needs to 
 apply to the server during installation. It looks at the image stream that it needs
 to apply and renders it to disk. It calls bootkube and waits for a temporary minimal control
 plane to come up and load the cluster version Operator.
+////
 
 During continuous update mode, two controllers run. One continuously updates
 the payload manifests, applies them to the cluster, and outputs the status of
 the controlled rollout of the Operators, whether they are available, upgrading,
-or failed. The second controller constantly checks with to Cincinnati to
+or failed. The second controller polls the {product-title} update service to
 determine if updates are available.