[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in upgrading/upgrade-operator.adoc

[agantony]

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

[openshift-ci-robot]

@agantony: This pull request references ROX-33164 which is a valid jira issue.

Details

In response to this:

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

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 openshift-eng/jira-lifecycle-plugin repository.

[ocpdocs-previewbot]

🤖 Fri May 08 16:26:18 - Prow CI generated the docs preview:

https://111431--ocpdocs-pr.netlify.app/openshift-acs/latest/cloud_service/upgrading-cloud/upgrade-cloudsvc-operator.html
https://111431--ocpdocs-pr.netlify.app/openshift-acs/latest/upgrading/upgrade-operator.html

[agantony]

PR Review Summary - ROX-33164 DITA Compatibility Fixes

Overview

This PR successfully addresses DITA conversion errors in the RHACS Operator upgrade documentation through strategic module refactoring and content quality improvements.

Key Accomplishments

🔄 Module Restructuring (4 new modules)

• Split operator-upgrade-change-subscription-channel.adoc into concept + 2 procedures (console & CLI)
• Extracted rollback-operator-upgrade.adoc concept
• Extracted operator-upgrade-troubleshooting.adoc concept
• Better adherence to Red Hat modular documentation standards

✅ DITA Compatibility

• Added missing abstracts to modules
• Standardized placeholder naming (<namespace_name>, <central_db_pod_name>)
• Converted output blocks to proper .Example output format
• Ensured content type attributes match module types

📝 Content Quality

• Improved clarity: "contains" → "has" (3 files)
• Grammar corrections: "which" → "that" for restrictive clauses
• Terminology consistency: "previous" → "earlier" (6 occurrences)
• Enhanced sentence structure and conciseness

📚 Assembly Improvements

• Moved embedded links to Additional Resources section
• Updated include structure for new modules
• Improved upgrade guidelines with proper xrefs

Files Changed: 14 (4 new, 9 modified, 1 assembly)

---

Review Navigation Guide

Main Assembly

📄 Operator Upgrade Assembly
🔗 Review on Netlify

Focus areas:

• Introduction with new Additional Resources section
• Restructured subscription channel section (now has 3 subsections)
• Rollback section organization
• Troubleshooting section structure

---

Prerequisites & Preparation

📄 Prepare for Operator Upgrades
🔗 View section
✏️ Clarity: "contains" → "has"

📄 Change Collection Method
🔗 View section
✏️ Improved abstract conciseness

---

Core Upgrade Procedures

📄 Change Subscription Channel (CONCEPT) ⭐ Refactored
🔗 View section
✏️ Changed from PROCEDURE to CONCEPT, extracted procedures to child modules

📄 Change Subscription Channel - Web Console 🆕 NEW
🔗 View section
✏️ Standalone procedure with prerequisites and 6-step workflow

📄 Change Subscription Channel - CLI 🆕 NEW
🔗 View section
✏️ Standalone procedure with oc patch command

---

Database Configuration

📄 Modify Central CR for External Database
🔗 View section
✏️ Added abstract, grammar fix ("which" → "that")

📄 Modify Central Custom Resource
🔗 View section
✏️ Multiple clarity improvements, consistent placeholders

---

Rollback Procedures

📄 Rollback Operator Upgrade (CONCEPT) 🆕 NEW
🔗 View section
✏️ Extracted concept with version constraints

📄 Rollback by Using CLI
🔗 View section
✏️ Example output formatting, "previous" → "earlier"

📄 Rollback by Using Web Console
🔗 View section
✏️ Added abstract, "previous" → "earlier"

---

Troubleshooting

📄 Troubleshooting Operator Upgrade Issues (CONCEPT) 🆕 NEW
🔗 View section
✏️ Extracted concept for troubleshooting section

📄 Central DB Scheduling Failure
🔗 View section
✏️ Title clarity, placeholder consistency, example output formatting

📄 Operator Fails to Deploy
🔗 View section
✏️ Added missing $ prompt

---

Review Checklist

DITA Compatibility ✅

• New modules have proper abstracts
• Content type attributes match module types (CONCEPT vs PROCEDURE)
• Example output blocks properly labeled
• Placeholder naming follows consistent convention

Content Quality ✅

• Grammar improvements applied
• Terminology consistency maintained
• Sentence clarity enhanced
• No content lost during refactoring

Module Structure ✅

• Concepts separated from procedures
• Prerequisites in appropriate modules
• Reusable modules support multiple contexts
• Logical include hierarchy in assembly

Next Steps

• Verify DITA build completes without errors
• Cherry-pick to rhacs-docs-4.10 and rhacs-docs-4.9

---

Issue: ROX-33164
Versions: 4.9+

[openshift-ci]

@agantony: 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.