OSDOCS#16913: CQA for next set of CLI assemblies

Author: bergerhoffer

cli_reference/openshift_cli/administrator-cli-commands.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-This reference provides descriptions and example commands for OpenShift CLI (`oc`) administrator commands. You must have `cluster-admin` or equivalent permissions to use these commands.
+[role="_abstract"]
+To learn more about the {oc-first} administrator commands, review their descriptions and example commands. You must have `cluster-admin` or equivalent permissions to use these commands.
 
 For developer commands, see the xref:../../cli_reference/openshift_cli/developer-cli-commands.adoc#cli-developer-commands[OpenShift CLI developer command reference].
 

cli_reference/openshift_cli/configuring-cli.adoc

@@ -6,6 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
+TODO
+
+// TODO move this below to module? so small though. Maybe just consider removing the umbrella heading
 [id="cli-enabling-tab-completion"]
 == Enabling tab completion
 

cli_reference/openshift_cli/developer-cli-commands.adoc

@@ -6,7 +6,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-This reference provides descriptions and example commands for OpenShift CLI (`oc`) developer commands.
+[role="_abstract"]
+To learn more about the {oc-first} developer commands, review their descriptions and example commands.
+
 ifdef::openshift-enterprise,openshift-origin[]
 For administrator commands, see the xref:../../cli_reference/openshift_cli/administrator-cli-commands.adoc#cli-administrator-commands[OpenShift CLI administrator command reference].
 endif::openshift-enterprise,openshift-origin[]

cli_reference/openshift_cli/extending-cli-plugins.adoc

@@ -6,8 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can write and install plugins to build on the default `oc` commands,
-allowing you to perform new and more complex tasks with the
+[role="_abstract"]
+You can write and install plugins to build on the default `oc` commands, allowing you to perform new and more complex tasks with the
 ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 {product-title}
 endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]

modules/cli-configuring-kubeconfig-using-cli.adoc

@@ -6,8 +6,14 @@
 [id="cli-accessing-kubeconfig-using-cli_{context}"]
 = Accessing kubeconfig by using the oc CLI
 
+[role="_abstract"]
 You can use the `oc` CLI to log in to your OpenShift cluster and retrieve a kubeconfig file for accessing the cluster from the command line.
 
+[IMPORTANT]
+====
+If you plan to reuse the exported `kubeconfig` file across sessions or machines, store it securely and avoid committing it to source control.
+====
+
 .Prerequisites
 
 * You have access to the {product-title} web console or API server endpoint.
@@ -18,12 +24,14 @@ You can use the `oc` CLI to log in to your OpenShift cluster and retrieve a kube
 +
 [source,terminal]
 ----
-$ oc login <api-server-url> -u <username> -p <password> <1><2><3>
+$ oc login <api_server_url> -u <username> -p <password>
 ----
 +
-<1> Specify the full API server URL. For example: `https://api.my-cluster.example.com:6443`.
-<2> Specify a valid username. For example: `kubeadmin`.
-<3> Provide the password for the specified user. For example, the `kubeadmin` password generated during cluster installation.
+where:
+
+`<api_server_url>`:: Specifies the full API server URL; for example, `https://api.my-cluster.example.com:6443`.
+`<username>`:: Specifies a valid username; for example, `kubeadmin`.
+`<password>`:: Specifies the password for the specified user; for example, the `kubeadmin` password generated during cluster installation.
 
 . Save the cluster configuration to a local file by running the following command:
 +
@@ -45,8 +53,3 @@ $ export KUBECONFIG=./kubeconfig
 ----
 $ oc get nodes
 ----
-
-[NOTE]
-====
-If you plan to reuse the exported `kubeconfig` file across sessions or machines, store it securely and avoid committing it to source control.
-====

modules/cli-extending-plugins-installing.adoc

@@ -6,15 +6,15 @@
 [id="cli-installing-plugins_{context}"]
 = Installing and using CLI plugins
 
+[role="_abstract"]
 After you write a custom plugin for the
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 {product-title}
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 ifdef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 OpenShift
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
-CLI, you must install
-the plugin before use.
+CLI, you must install the plugin before use.
 
 .Prerequisites
 
@@ -50,19 +50,15 @@ The following compatible plugins are available:
 /usr/local/bin/<plugin_file>
 ----
 +
-If your plugin is not listed here, verify that the file begins with `oc-`
-or `kubectl-`, is executable, and is on your `PATH`.
+If your plugin is not listed here, verify that the file begins with `oc-` or `kubectl-`, is executable, and is on your `PATH`.
 . Invoke the new command or option introduced by the plugin.
 +
-For example, if you built and installed the `kubectl-ns` plugin from the
- link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository],
-  you can use the following command to view the current namespace.
+For example, if you built and installed the `kubectl-ns` plugin from the link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository], you can use the following command to view the current namespace.
 +
 [source,terminal]
 ----
 $ oc ns
 ----
 +
 Note that the command to invoke the plugin depends on the plugin file name.
-For example, a plugin with the file name of `oc-foo-bar` is invoked by the `oc foo bar`
-command.
+For example, a plugin with the file name of `oc-foo-bar` is invoked by the `oc foo bar` command.

modules/cli-extending-plugins-writing.adoc

@@ -6,33 +6,27 @@
 [id="cli-writing-plugins_{context}"]
 = Writing CLI plugins
 
+[role="_abstract"]
 You can write a plugin for the
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 {product-title}
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 ifdef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 OpenShift
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
-CLI in any programming language
-or script that allows you to write command-line commands. Note that you can not
-use a plugin to overwrite an existing `oc` command.
+CLI in any programming language or script that allows you to write command-line commands. Note that you cannot use a plugin to overwrite an existing `oc` command.
 
-.Procedure
+This procedure creates a simple Bash plugin that prints a message to the terminal when the `oc foo` command is issued.
 
-This procedure creates a simple Bash plugin that prints a message to the
-terminal when the `oc foo` command is issued.
+.Procedure
 
 . Create a file called `oc-foo`.
 +
 When naming your plugin file, keep the following in mind:
 
 * The file must begin with `oc-` or `kubectl-` to be recognized as a
 plugin.
-* The file name determines the command that invokes the plugin. For example, a
-plugin with the file name `oc-foo-bar` can be invoked by a command of
-`oc foo bar`. You can also use underscores if you want the command to contain
-dashes. For example, a plugin with the file name `oc-foo_bar` can be invoked
-by a command of `oc foo-bar`.
+* The file name determines the command that invokes the plugin. For example, a plugin with the file name `oc-foo-bar` can be invoked by a command of `oc foo bar`. You can also use underscores if you want the command to contain dashes. For example, a plugin with the file name `oc-foo_bar` can be invoked by a command of `oc foo-bar`.
 
 . Add the following contents to the file.
 +
@@ -56,20 +50,18 @@ fi
 
 echo "I am a plugin named kubectl-foo"
 ----
-
++
 After you install this plugin for the
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 {product-title}
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 ifdef::openshift-rosa,openshift-rosa-hcp[]
 OpenShift
 endif::openshift-rosa,openshift-rosa-hcp[]
-CLI, it can be invoked
-using the `oc foo` command.
+CLI, it can be invoked using the `oc foo` command.
 
 [role="_additional-resources"]
 .Additional resources
 
-* Review the link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository]
-for an example of a plugin written in Go.
-* Review the link:https://github.com/kubernetes/cli-runtime/[CLI runtime repository] for a set of utilities to assist in writing plugins in Go.
+* link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository]
+* link:https://github.com/kubernetes/cli-runtime/[CLI runtime repository]

modules/oc-adm-by-example-content.adoc

@@ -6,6 +6,9 @@
 [id="openshift-cli-admin_{context}"]
 = OpenShift CLI (oc) administrator commands
 
+[role="_abstract"]
+Review the commands that cluster administrators can use to configure, maintain, and troubleshoot OpenShift Container Platform clusters.
+
 
 
 == oc adm build-chain

modules/oc-by-example-content.adoc

@@ -6,6 +6,9 @@
 [id="openshift-cli-developer_{context}"]
 = OpenShift CLI (oc) developer commands
 
+[role="_abstract"]
+Review the commands that developers can use to create, deploy, and manage applications on OpenShift Container Platform clusters.
+
 
 
 == oc annotate