Bug 1875852

Document URL
============

Red Hat OpenShift Container Storage 4.5
Deploying and managing OpenShift Container Storage using Google Cloud

https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html-single/deploying_and_managing_openshift_container_storage_using_google_cloud/index?lb_target=preview#replacing-storage-nodes_gcp

Section Number and Name
=======================

Chapter 9. Replacing storage nodes

Sections:

- 9.1. Replacing operational nodes on Google Cloud installer-provisioned infrastructure
- 9.2. Replacing failed nodes on Google Cloud installer-provisioned infrastructure

Describe the issue
==================

First two steps of the procedure listed in section 9.1 notes:

- Log in to OpenShift Web Console and click Compute → Nodes.
- Identify the node that needs to be replaced. Take a note of its Machine Name.

This has few minor issues:

- "Machine Name" of a node is not directly visible on list of Nodes (where the
  reader would be looking for it based on the docs) nor a even a Node page, so
  suggesting to node down this info could cause confusion (screenshot #1)
- Figuring out machine name based on a node selected in a node list is not
  exactly straightforward (if one tries to do that in this situation): Nodes
  page -> page of a Node -> Details tab -> Machine entry
- Following few steps operates with node name, so a confused reader could be
  thinking that the previous note about machine name is a typo
- When the steps starts to discuss Machine CR again, it navigates the reader
  to list of machines (Click Compute -> Machines) - but at this point, one can
  see both node and machine names in this list (see screenshot #2)

A similar issue is present in section 9.2 which navigates a reader to Nodes
page, but then asks a reader to click on it's Machine name. Again, there is
no such information present in Nodes page. Moreover it's not clear whether
one should edit annotation on affected machine or a node.

Suggestions for improvement
===========================

Section 9.1:

- Instead of suggesting to note down Machine name in step #2, suggest to note
  down node name.
- Then when locating a Machine for the node is necessary in step #5, tell the
  reader that one could locate the machine via it's node name (as list of
  Machines in OCP Console conveniently contains both node and machine names)

Section 9.2: a similar suggestion apply: first identify problematic node on a
node list, and then find a matching machine using node name on a machine list.
For each step of the procedure, it should be clear if it applies to a node or
a machine.

Additional information
======================

This problem seems to be there since OCS 4.2 docs. All other places which
talks about this procedure are likely to be affected by the same problem, not
just GCP guide.