OSDOCS-17011 Bare Metal Install CQA 1

[cbippley]

Version(s): 4.20+

Issue:OSDOCS-17011

Link to docs preview:

QE review:

• QE has approved this change.

Additional information:

[ocpdocs-previewbot]

🤖 Fri May 08 15:48:19 - Prow CI generated the docs preview:

https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html
https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/ipi/ipi-install-prerequisites.html
https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/preparing-to-install-on-bare-metal.html

[openshift-ci]

@cbippley: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[cbippley]

PR Review Summary - OSDOCS-17011: Bare Metal Install CQA 1

This PR implements Content Quality Assessment (CQA 2.1) improvements for bare metal installation documentation, focusing on DITA compatibility and Red Hat Style Guide compliance across 9 files.

Summary of Changes

Total Changes: 9 files modified (+178 additions, -159 deletions)

Change Categories:

1. DITA Compatibility Enhancements (All 9 files)

   • Added [role="_abstract"] attributes to mark short descriptions in 7 modules
   • Converted numbered callouts to where: definition lists for better semantic structure
   • Standardized "Example output:" formatting (removed .Example output block titles)
   • Improved prerequisite and procedure section formatting

2. Style Guide Compliance (8 files)

   • Standardized "bare metal" vs "bare-metal" usage (hyphenated when adjective: "bare-metal node", unhyphenated when standalone: "on bare metal")
   • Fixed "RedFish" → "Redfish" capitalization (proper trademark format)
   • Fixed "baremetal" → "bare-metal" in network and API references
   • Removed inline hyperlinks in favor of xref links in Additional resources sections

3. Content Reorganization (2 files)

   • Restructured "Preparing for bare-metal cluster installation" assembly for better flow
   • Moved all Additional resources to a consolidated section at the end
   • Reorganized prerequisites to be more concise
   • Enhanced section hierarchy and grouping

---

Step-by-Step Review Guide

Assembly Files

1. Bare Metal Expanding the Cluster (Assembly)

• File: installing/installing_bare_metal/bare-metal-expanding-the-cluster.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html
• Changes:
  • Added [role="_abstract"] attribute for short description
  • Fixed "RedFish" → "Redfish" capitalization (2 instances)
  • Removed duplicate Additional resources links
  • Removed trailing whitespace from xref
• What to review:
  • Abstract displays correctly
  • Redfish Virtual Media references are consistently capitalized
  • Additional resources section at bottom is clean

2. Preparing for Bare-Metal Cluster Installation (Assembly) - MAJOR RESTRUCTURE

• File: installing/installing_bare_metal/preparing-to-install-on-bare-metal.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/preparing-to-install-on-bare-metal.html
• Changes:
  • Changed title: "bare metal" → "bare-metal" (adjective)
  • Added abstract describing the assembly purpose
  • Simplified Prerequisites section (removed bullets, made more concise)
  • Removed inline hyperlinks from installation method descriptions
  • Changed section levels: subsections promoted to level-2 sections
  • Moved virtualization and SR-IOV content after installation methods
  • Consolidated all Additional resources into single section at end with proper xrefs
  • Fixed "bare metal" → "bare-metal" throughout (6+ instances)
  • Added three additional installation method descriptions
• What to review:
  • Overall assembly structure and flow
  • Installation method descriptions are clear without inline links
  • Section hierarchy makes sense
  • All Additional resources are properly linked and render correctly
  • Prerequisites are easy to scan

---

Module Files

Cluster Expansion and Node Preparation

3. Diagnosing Duplicate MAC Address

• File: modules/ipi-install-diagnosing-duplicate-mac-address.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html#ipi-install-diagnosing-duplicate-mac-address_bare-metal-expanding-the-cluster
• Changes:
  • Added abstract
  • Removed redundant intro sentence ("To determine whether...")
  • Standardized example output format (2 instances: .Example output → Example output:)
• What to review: Abstract and procedure flow, example output formatting

4. Preparing the Bare-Metal Node - EXTENSIVE CHANGES

• File: modules/ipi-install-preparing-the-bare-metal-node.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html#preparing-the-bare-metal-node_bare-metal-expanding-the-cluster
• Changes:
  • Changed title: "bare metal" → "bare-metal"
  • Added abstract
  • Removed block title from Important admonition
  • Fixed "bare metal" → "bare-metal" throughout (12+ instances)
  • Fixed "RedFish" → "Redfish"
  • Converted 12 numbered callouts to where: definition lists (both static and DHCP YAML examples)
  • Standardized example output format (2 instances)
• What to review:
  • YAML examples with new where: explanations (static config has 12 explanations, DHCP has 8)
  • Terminology consistency
  • Example output formatting

5. Preparing to Deploy with Virtual Media on the Bare-Metal Network

• File: modules/ipi-install-preparing-to-deploy-with-virtual-media-on-the-baremetal-network.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html#preparing-to-deploy-with-virtual-media-on-the-bare-metal-network_bare-metal-expanding-the-cluster
• Changes:
  • Changed ID: "baremetal" → "bare-metal"
  • Changed title: "baremetal" → "bare-metal" (inline code format for network name)
  • Added abstract
  • Fixed "baremetal" → "bare-metal" network references (5 instances)
  • Fixed apiVersion: "baremetal" → "bare-metal"
  • Converted 3 callouts to where: definition lists
• What to review:
  • Network name formatting (backticks for bare-metal network)
  • YAML examples with where: explanations
  • Prerequisites clarity

6. Provisioning the Bare-Metal Node

• File: modules/ipi-install-provisioning-the-bare-metal-node.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html#provisioning-the-bare-metal-node_bare-metal-expanding-the-cluster
• Changes:
  • Changed title: "bare metal" → "bare-metal"
  • Added abstract
  • Fixed "bare metal" → "bare-metal" throughout (5 instances)
• What to review: Terminology consistency, procedure clarity

7. Replacing a Bare-Metal Control Plane Node

• File: modules/ipi-install-replacing-a-bare-metal-control-plane-node.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html#replacing-a-bare-metal-control-plane-node_bare-metal-expanding-the-cluster
• Changes:
  • Added abstract
  • Fixed cluster operator name: "baremetal" → "bare-metal" in command
  • Fixed example output: "baremetal" → "bare-metal"
  • Fixed apiVersion: "baremetal" → "bare-metal"
  • Converted 5 callouts to where: definition lists
  • Standardized example output format (3 instances)
  • Fixed "bare metal" → "bare-metal" terminology (3 instances)
• What to review:
  • BareMetalHost YAML with where: explanations
  • Example outputs show correct bare-metal operator name
  • Command examples are accurate

Networking and Virtualization

8. NIC Partitioning for SR-IOV Devices

• File: modules/nw-sriov-dual-nic-con.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/preparing-to-install-on-bare-metal.html#nw-sriov-dual-nic-con_preparing-to-install-on-bare-metal
• Changes:
  • Moved abstract attribute to correct position (after paragraph, not title)
• What to review: Abstract displays correctly for SR-IOV concept

9. Planning Bare-Metal Cluster for OpenShift Virtualization

• File: modules/virt-planning-bare-metal-cluster-for-ocp-virt.adoc
• Netlify Preview: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/preparing-to-install-on-bare-metal.html#virt-planning-bare-metal-cluster-for-ocp-virt_preparing-to-install-on-bare-metal
• Changes:
  • Fixed sentence structure: split run-on sentence with period
  • Changed "and a minimum" → ". A minimum" for better readability
• What to review: Sentence clarity in live migration requirements

---

Review Checklist

DITA Compatibility

• All abstract role attributes render correctly
• Definition lists for "where:" explanations are readable and well-formatted
• Example output formatting is consistent (no block titles)
• No rendering errors in Netlify preview

Style Guide Compliance

• "bare metal" (noun) vs "bare-metal" (adjective/network name) usage is correct
• "Redfish" capitalization is consistent (not "RedFish")
• Network names like bare-metal use inline code format where appropriate
• API versions use correct naming conventions
• Cluster operator names are correct ("bare-metal" not "baremetal")

Content Quality

• Assembly restructuring improves content flow and discoverability
• Prerequisites are clear and scannable
• Procedures are complete with all necessary steps
• YAML examples with "where:" explanations are helpful and accurate
• All cross-references and links work correctly

Technical Accuracy

• YAML examples are syntactically correct
• Command examples reference correct resource names
• apiVersion fields are accurate
• BMC protocols (Redfish) are correctly named
• Network terminology is technically accurate

---

Key Changes to Pay Special Attention To

1. Major Assembly Restructure (File #2)

The "Preparing for bare-metal cluster installation" assembly has been significantly reorganized:

• Prerequisites simplified: From bulleted list to concise statements
• Section hierarchy changed: Installation methods are now level-2 sections instead of subsections
• Content reordered: Virtualization planning and SR-IOV moved after installation methods
• Additional resources consolidated: All resources moved to single section at end
• Inline links removed: External links moved to Additional resources section

Review focus: Verify the new structure improves usability and all content is still accessible.

2. Extensive Callout-to-Definition-List Conversions

Multiple files converted numbered callouts (<1>, <2>, etc.) to where: definition lists:

• File Fixed doc files to meet AsciiDoctor standards #4 (Preparing the Bare-Metal Node): 20 callouts → definition list entries (2 YAML examples)
• File Revised build system to make Guard useful. #5 (Virtual Media): 3 callouts → definition list entries
• File Doc'ed distro handling and added distro support to builder #7 (Replacing Control Plane): 5 callouts → definition list entries

Review focus: Ensure definition lists are more readable than callouts and all explanations are preserved.

3. Terminology Standardization

Comprehensive terminology fixes across all files:

• "bare metal" vs "bare-metal": 30+ instances corrected
• "Redfish" capitalization: 4 instances corrected
• "baremetal" → "bare-metal": Network names, API versions, operator names (10+ instances)

Review focus: Verify terminology is consistently applied and technically accurate.

---

Testing Notes

Primary Test Pages

1. Main expansion guide: https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/bare-metal-expanding-the-cluster.html

   • Contains modules Initial build system #3-7

2. Preparation guide (restructured): https://111319--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_bare_metal/preparing-to-install-on-bare-metal.html

   • Major restructure - review entire page flow
   • Contains modules Migration of Cart Spec Guide topics #8-9

Key Test Areas

1. YAML Examples: Scroll through both static and DHCP configuration examples in module Fixed doc files to meet AsciiDoctor standards #4 to verify where: definition lists display correctly
2. Additional Resources: Check the consolidated Additional resources section at the end of the preparation guide (file Added client tools install topics #2)
3. Section Navigation: Verify the new section hierarchy in the preparation guide makes sense
4. Code Formatting: Check that bare-metal network names display with inline code formatting
5. Example Outputs: Verify all example outputs render correctly without block titles
6. Links: Test all xref links in the Additional resources section

---

File-by-File Change Summary

File	Lines Changed	Key Changes
bare-metal-expanding-the-cluster.adoc	+3/-5	Abstract, Redfish fixes, cleanup
preparing-to-install-on-bare-metal.adoc	+49/-42	Major restructure, abstract, terminology
ipi-install-diagnosing-duplicate-mac-address.adoc	+3/-4	Abstract, formatting
ipi-install-preparing-the-bare-metal-node.adoc	+70/-70	Extensive: abstract, terminology, 20 callouts→definitions
ipi-install-preparing-to-deploy-with-virtual-media...	+21/-12	Abstract, network terminology, 3 callouts→definitions
ipi-install-provisioning-the-bare-metal-node.adoc	+6/-5	Abstract, terminology
ipi-install-replacing-a-bare-metal-control-plane-node.adoc	+24/-20	Abstract, terminology, 5 callouts→definitions
nw-sriov-dual-nic-con.adoc	+1/-0	Abstract position fix
virt-planning-bare-metal-cluster-for-ocp-virt.adoc	+1/-1	Sentence structure

Total: 9 files, +178 additions, -159 deletions