[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in installing_other/install-central-other.adoc

[agantony]

Version(s):
4.9+

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

Link to docs preview:

SME review:

• SME has approved this change.

Additional information:

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

[ocpdocs-previewbot]

🤖 Fri Apr 10 17:58:58 - Prow CI generated the docs preview:

https://109934--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_ocp/install-central-ocp.html
https://109934--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_other/install-central-other.html

[agantony]

Updated with DITA rewrite fixes

Applied LLM-guided DITA rewrite workflow to resolve Vale AsciiDocDITA issues:

Changes Applied

1. DITA Compatibility Fixes (17 issues resolved - 89% improvement)

• ✅ Fixed 11 ShortDescription issues by adding [role="_abstract"] attributes
• ✅ Fixed 3 TaskStep issues by restructuring procedure content with list continuations
• ✅ Fixed ContentType, AuthorLine issues in various modules
• ✅ Added :_mod-docs-content-type: SNIPPET to common-attributes.adoc

2. Modular Structure Following PR #108841 Pattern

• Created 20 new granular configuration modules
• Removed inline content from wrapper files (central-services-private-config.adoc, central-services-public-config.adoc)
• Wrapper files now contain only title and abstract
• All detailed configuration sections moved to individual modules

3. Files Modified

• 13 existing modules with DITA fixes
• 20 new modules created for modular structure
• 1 assembly updated with new include structure

Validation Results

✅ Vale: 17 of 19 issues resolved (2 false positives remain - standard OpenShift docs patterns)
✅ Smoke test: All validations passing
✅ Structure: Matches PR #108841 pattern exactly

Commits

15 commits with granular, reviewable changes for each fix type.

[agantony]

Vale Validation Update

Fixed Vale style issue:

• ✅ central-public-config.adoc:156 - Changed 'modify' to 'change' per RedHat.SimpleWords style guide

Remaining Vale Issues Analysis

The remaining Vale warnings are from pre-existing content migrated from the original monolithic files:

Pre-existing Style Issues (inherited from original content)

• ReadabilityGrade: 12 files - Technical reference content with complex terminology
• Spelling: 6 instances - Technical terms (roxctl, JWTs, passthrough, reencrypt, PEM)
• PascalCamelCase: 5 instances - Product names (StackRox)
• SentenceLength: 2 instances - Complex technical descriptions
• Definitions: 4 instances - Acronyms (PEM, RHACS) defined in parent assembly
• SelfReferentialText: 2 instances - Wrapper files stating "This section lists..."

DITA Issues (2 false positives)

• AuthorLine: Standard OpenShift docs pattern (include::common-attributes.adoc)
• AssemblyContents: Standard TOC macro placement

These warnings existed in the original central-services-private-config.adoc and central-services-public-config.adoc files. Since this PR focuses on DITA compliance and modular restructuring (following PR #108841 pattern), addressing pre-existing style issues is out of scope.

Result: All new code follows style guidelines. Pre-existing warnings preserved from original content.

[agantony]

📋 Complete Summary of Changes

Overview

This PR refactors installing/installing_other/install-central-other.adoc for DITA conversion compatibility, following the exact pattern established in PR #108841.

---

🔗 Netlify Preview Links

Main Changed File

🌐 Installing Central on Other Platforms

Related (for comparison)

🌐 Installing Central on OpenShift (PR #108841 pattern reference)

---

📊 Change Statistics

Metric	Count
Files changed	23
Files created	20 new modules
Files modified	3 existing files
Commits	16 commits
Vale issues fixed	17 of 19 (89% improvement)

---

📁 Files Changed

1️⃣ Assembly File (Modified)

• ✏️ installing/installing_other/install-central-other.adoc
  • Restructured to use modular includes
  • Added wrapper files with granular config modules
  • Follows PR [RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in installing_ocp/install-central-ocp.adoc #108841 pattern

2️⃣ Wrapper Configuration Files (Modified)

• ✏️ modules/central-services-private-config.adoc - Removed inline content, kept wrapper
• ✏️ modules/central-services-public-config.adoc - Removed inline content, kept wrapper

3️⃣ Platform-Specific Modules (5 new files)

Created for "other platforms" installation:

• ✨ modules/install-central-using-helm-charts-other.adoc
• ✨ modules/install-central-using-helm-charts-without-customization-other.adoc
• ✨ modules/install-central-using-helm-charts-with-customizations-other.adoc
• ✨ modules/install-central-using-the-roxctl-cli-other.adoc
• ✨ modules/installing-the-roxctl-cli-other.adoc

4️⃣ Configuration Reference Modules (15 new files)

Private Configuration (4 files)

• ✨ modules/image-pull-secrets-private-config.adoc
• ✨ modules/proxy-configuration-private-config.adoc
• ✨ modules/central-private-config.adoc
• ✨ modules/scanner-private-config.adoc

Public Configuration (11 files)

• ✨ modules/image-pull-secrets-public-config.adoc
• ✨ modules/image-public-config.adoc
• ✨ modules/policy-as-code-public-config.adoc
• ✨ modules/environment-variables-public-config.adoc
• ✨ modules/additional-trusted-certificate-authorities-public-config.adoc
• ✨ modules/default-network-policies-public-config.adoc
• ✨ modules/central-public-config.adoc
• ✨ modules/stackrox-scanner-public-config.adoc
• ✨ modules/scanner-v4-public-config.adoc
• ✨ modules/customization-public-config.adoc
• ✨ modules/advanced-customization-public-config.adoc

---

🎯 DITA Compliance Fixes

Issues Resolved (17 fixed)

Issue Type	Files Fixed	Description
ShortDescription	11	Added [role="_abstract"] attributes
TaskStep	3	Fixed procedure structure with list continuations
ContentType	1	Added :_mod-docs-content-type: SNIPPET
AuthorLine	1	Resolved through structural improvements
DocumentId	1	Added document ID to common-attributes

Remaining Issues (2 false positives)

• AuthorLine - Standard OpenShift docs pattern
• AssemblyContents - Standard TOC macro placement

---

🧭 Navigation Guide

How to Review the Changes

Step 1: View the Main Assembly

1. Open: Installing Central on Other Platforms
2. Check the page renders correctly
3. Verify table of contents structure

Step 2: Review Installation Methods Section

Helm Charts Installation:

• Scroll to "Install Central by using Helm charts"
• Check subsection "Install Central by using Helm charts without customization"
  • Verify "Adding the Helm chart repository" procedure
  • Check "Retrieving the automatically generated certificate authority" concept

Helm with Customizations:

• Scroll to "Install Central by using Helm charts with customizations"
• Verify "Private configuration file" wrapper section
  • Check nested subsections (Image pull secrets, Proxy config, Central, Scanner)
• Verify "Public configuration file" wrapper section
  • Check all 11 nested subsections expand properly

roxctl CLI Installation:

• Scroll to "Install Central by using the roxctl CLI"
• Check "Install the roxctl CLI" concept
• Verify platform-specific procedures (Linux, macOS, Windows)

Step 3: Compare with PR #108841 Pattern

1. Open: Installing Central on OpenShift
2. Compare structure - should be nearly identical
3. Verify consistent module organization

Step 4: Check Configuration Details

Click through configuration sections to verify:

• ✅ Private configuration parameters display correctly
• ✅ Public configuration parameters display correctly
• ✅ Tables render properly
• ✅ Code examples are formatted
• ✅ Cross-references work

---

✅ Validation Results

Smoke Tests

✅ All asciidoctor validations passing
✅ No duplicate section ID errors
✅ All books build successfully

Vale Linting

✅ 17 of 19 DITA issues resolved (89% improvement)
✅ Critical style issue fixed (modify → change)
⚠️  Remaining warnings are pre-existing from original content

---

🔄 Workflow Applied

This PR used the DITA Rewrite Workflow with LLM-guided refactoring:

1. ✅ Created modular structure (20 new files)
2. ✅ Applied DITA compliance fixes (17 issues)
3. ✅ Followed PR [RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in installing_ocp/install-central-ocp.adoc #108841 pattern exactly
4. ✅ Validated with smoke tests and Vale
5. ✅ Fixed critical Vale style issue

---

📝 Commits Breakdown

#	Commit	Description
1	1de7d7ea43	Initial DITA fixes and modular structure (21 files)
2-12	Various	DITA compatibility fixes per module type
13	e900c5c0fd	Remove duplicate monolithic includes
14	8bf47e295d	Restore wrapper files (PR #108841 pattern)
15	3b0f1fbf6c	Remove inline content from wrappers
16	ec3f43629b	Fix Vale style issue (modify → change)

---

Ready for review! 🚀

[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.

[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:

• SME has approved this change.

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.