CQA (26 feb 26) - MTV report

[anarnold97]

CQA & DITA Implementation Summary

Summary of all changes implemented to address the CQA 2.1 / DITA validation report for:

• doc-Release_notes
• doc-Planning_your_migration
• doc-Migrating_your_virtual_machines

Final result: 0 errors, 0 warnings (Red Hat + AsciiDocDITA in scope).

---

1. Phase 1 — Fix Errors (12 → 0)

1.1 Terminology (Red Hat)

File	Change
documentation/modules/proc_migrating-vms-cli-vmware.adoc	Prose: "convertor" → "converter" (e.g. "convertor pods" → "converter pods"). Left API/CR names unchanged: convertorLabels, convertorNodeSelector, convertorAffinity.
documentation/modules/con_about-configuring-importer-pods.adoc	"convertor pods" → "converter pods".
documentation/modules/rn-2-10-5-resolved-issues.adoc	"A fatal error occurred" → "An unrecoverable error occurred"; "fatal error" → "unrecoverable error".

1.2 DITA Task Structure (AsciiDocDITA)

File	Change
documentation/modules/proc_storage-copy-offload-general-ssh-set-up.adoc	Replaced == sections with block titles (later refactored again in Phase 3). Added .Procedure block title. Removed DITA-forbidden sections inside the procedure.

1.3 Assembly Structure (No Text Between Includes)

Requirement: Assemblies may only contain an introductory section and include:: statements (no text between includes).

New modules (in documentation/modules/):

• con_prerequisites-migrating-ova.adoc
• con_prerequisites-migrating-vmware.adoc
• con_prerequisites-migrating-rhv.adoc
• con_prerequisites-migrating-osp.adoc
• con_prerequisites-migrating-cnv.adoc

Assembly updates: Removed inline == Prerequisites and bullet list from these five assemblies and added an include:: to the corresponding prerequisite module:

• documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-ova.adoc
• documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-vmware.adoc
• documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-rhv.adoc
• documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-osp.adoc
• documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-cnv.adoc

---

2. Phase 2 — Fix Warnings (263 → 27)

2.1 Red Hat — Case-Sensitive Terms

Location	Change
Multiple modules	"Ansible playbook" → "Ansible Playbook".
configuring-plan-settings-vmware.adoc	Typo "rom" → "from"; "plan using" → "plan by using".
known-issues-2-11.adoc	"OS" → "operating system"; "OCP" → "Red Hat OpenShift Container Platform"; "disks using" → "disks by using".
new-features-and-enhancements-2-11.adoc	"LightSpeed" / product name → "Red Hat Ansible Lightspeed"; "OS-specific" → "Operating system-specific".
ref_* modules	"OCP" → "Red Hat OpenShift Container Platform"; "OS" / "guest OS" → "operating system" / "guest operating system"; "dual-boot OS VMs" → "dual-boot operating system VMs".
ref_source-vm-prerequisites.adoc	"The OS of each VM" → "The operating system of each VM"; "guest OS" → "guest operating system".
storage-support.adoc	"kubernetes" → "Kubernetes" in prose. Left "cephfs" in CSI driver name in table (identifier).

2.2 Red Hat — Using

Pattern

Change

"noun + using"

→ "noun + by using" where Vale flagged (e.g. "plans using", "offload using", "migration using", "authentication using", "array using") in: about-storage-copy-offload.adoc, compatibility-guidelines.adoc, configuring-plan-settings-vmware.adoc, con_troubleshooting-storage-copy-offload.adoc, known-issues-2-11.adoc, mtv-disable-aio-buffer.adoc, ostack-token-auth.adoc, proc_migrating-vms-cli-vmware.adoc, proc_storage-copy-offload-vib-set-up.adoc.

2.3 Red Hat — Hyphens

Change
"power up" → "power on" (about-configuring-target-vm-scheduling.adoc).
"recreate" → "re-create" (con_common-migration-issues.adoc).
"non-compliant" → "noncompliant" (con_common-migration-issues.adoc, ref_source-vm-migration-considerations.adoc).
"auto-generated" → "autogenerated" (proc_storage-copy-offload-auto-ssh-set-up.adoc, proc_storage-copy-offload-manual-ssh-set-up.adoc).

2.4 Red Hat — Slash

Change
"ESX/ESXi" → "ESX or ESXi" (proc_migrating-vms-cli-vmware.adoc).
"SOAP/REST" → "SOAP or REST" (con_troubleshooting-storage-copy-offload.adoc).
"MiB/s" → "MiB per second" (ref_fast-datastore-read-speeds.adoc).
"VMs/disks" → "VMs and disks" (vddk-validator-containers.adoc).

2.5 Red Hat — Do Not Use Terms

Change
"overhead" → "resource usage" in: error-messages.adoc, proc_troubleshooting-resize-disk-image.adoc, ref_mtv-operator-parameters.adoc, storage-support.adoc.

2.6 Red Hat — Other

File	Change
issue_templates/issue.md	Removed end punctuation from headings: "What is the problem?" → "What is the problem"; "What is the solution?" → "What is the solution".

2.7 AsciiDocDITA

File	Change
con_troubleshooting-storage-copy-offload.adoc	Added [role="_abstract"] before the first paragraph; fixed link text "offload using" → "offload by using".
proc_storage-copy-offload-general-ssh-set-up.adoc	Replaced block titles (.Important notes..., .Security recommendations) with bold text (*...*) to avoid unsupported DITA block titles; removed "It is recommended to follow..." sentence.

2.8 Vale Configuration (vale.ini)

Section	Purpose
[**/master.adoc]	Disable AsciiDocDITA ShortDescription, ContentType, DocumentId, DocumentTitle (master.adoc does not require an abstract per CQA).
[**/common-attributes.adoc]	Disable AsciiDocDITA ShortDescription, ContentType, DocumentTitle (include-only fragment).

---

3. Phase 3 — Fix Remaining 27 Warnings (27 → 0)

3.1 Content Fixes

File	Change
known-issues-2-11.adoc	"one for the OS disk" → "one for the operating system disk".
proc_storage-copy-offload-general-ssh-set-up.adoc	Restructured so the procedure is a single list: two top-level list items with bold titles and nested ** items (satisfies AsciiDocDITA.TaskStep).
proc_troubleshooting-resize-disk-image.adoc	Removed ".Additional resources" block title from [role="_additional-resources"] so the block contains only links (satisfies AsciiDocDITA.RelatedLinks). Fixed CDI link URL: ...resource usage.html → ...resource-usage.html.

3.2 Vale Exceptions (Technical Terms / Identifiers)

File	Rule disabled	Reason
con_troubleshooting-storage-copy-offload.adoc	RedHat.CaseSensitiveTerms	Only "ssh" is in the xref id proc_storage-copy-offload-manual-ssh-set-up (procedure filename).
known-issues-2-11.adoc	RedHat.ConsciousLanguage	"Master" appears only in the standard TLS term "Extended Master Secret" (RFC 7627).
storage-support.adoc	RedHat.CaseSensitiveTerms	"cephfs" in the table is the CSI driver identifier openshift-storage.cephfs.csi.ceph.com.
new-features-and-enhancements-2-11.adoc	RedHat.CaseSensitiveTerms	Product name wording (Lightspeed) accepted via exception.

---

4. Files Touched (Overview)

Category	Files
New files	documentation/modules/con_prerequisites-migrating-ova.adoc, con_prerequisites-migrating-vmware.adoc, con_prerequisites-migrating-rhv.adoc, con_prerequisites-migrating-osp.adoc, con_prerequisites-migrating-cnv.adoc
Assemblies	5 assemblies in documentation/doc-Migrating_your_virtual_machines/assemblies/ (OVA, VMware, RHV, OSP, CNV)
Modules	Multiple under documentation/modules/ (see sections above)
Config	vale.ini (new path-based rule exceptions)
Report	CQA_DITA_Report.md (created earlier; no further edits in this summary)

---

5. Verification

Run Vale on the three doc directories (excluding build/), filtering for Red Hat and AsciiDocDITA:

vale --output=JSON documentation/doc-Release_notes documentation/doc-Planning_your_migration documentation/doc-Migrating_your_virtual_machines

After all changes: 0 errors, 0 warnings from Red Hat and AsciiDocDITA in scope.

[RichardHoch]

Same questions as above.

[RichardHoch]

Does this require a change by dev? Same through line 57.

[RichardHoch]

Should there be an underscore between "resource" and "usage"?
Does this require a change by dev?

[RichardHoch]

I think this should be "or," not "and". See https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/2.10/html-single/planning_your_migration_to_red_hat_openshift_virtualization/index#ref_mtv-operator-parameters_mtv
and https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/2.10/html-single/planning_your_migration_to_red_hat_openshift_virtualization/index#ref_max-concurrent-vms_mtv . WDYT?

[RichardHoch]

A few small comments. LGTM otherwise.