[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing Vale errors in installing/uninstall-acs.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.9
  • rhacs-docs-4.10

[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.9
  • rhacs-docs-4.10

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.

[agantony]

Summary

DRY-RUN MODE - No changes were made to files.

Analyzed AsciiDoc files in installing/uninstall-acs.adoc for DITA conversion compatibility using LLM-guided analysis.

Files Analyzed

5 files were analyzed:

File	Issues Found	Assessment
installing/uninstall-acs.adoc	2	Likely false positives or acceptable patterns
modules/common-attributes.adoc	0	No issues
modules/delete-acs-namespace.adoc	0	No issues
modules/delete-acs-global-resources.adoc	0	No issues
modules/delete-acs-label-annotation.adoc	0	No issues

Vale Validation Results (Actionable Issues Only)

Metric	Count
Issues found	2
Issues requiring fixes	0
Acceptable patterns	2

Issues Found (Dry-Run Analysis)

Rule	Count	Location	Assessment
AsciiDocDITA.AuthorLine	1	installing/uninstall-acs.adoc:4	False positive - this is a common-attributes include, not an author line
AsciiDocDITA.AssemblyContents	1	installing/uninstall-acs.adoc:7	Acceptable pattern - toc::[] and abstract follow common-attributes include

Issue Details

File:Line	Rule	Message	Analysis
installing/uninstall-acs.adoc:4	AuthorLine	Author lines are not supported for topics.	False positive: Line 4 contains include::modules/common-attributes.adoc[], which is a standard attribute include, not an author line. This is necessary for attribute resolution throughout the assembly.
installing/uninstall-acs.adoc:7	AssemblyContents	Content other than additional resources cannot follow include directives.	Acceptable pattern: The file follows a standard assembly structure: attributes → toc::[] → abstract → module includes. The common-attributes include at line 4 is a special case that provides attribute definitions. The assembly content (toc and abstract) correctly appears before the module includes (lines 21-25). This structure is widely used and DITA-compatible.

Recommended Actions

Based on dry-run analysis:

1. AuthorLine issue (line 4):

   • No action required
   • This is a false positive from the Vale rule
   • The include directive is correctly placed and necessary
   • Consider adjusting the Vale rule to exclude common-attributes includes

2. AssemblyContents issue (line 7):

   • No action required
   • The current structure is a standard and acceptable assembly pattern
   • Common-attributes includes are typically placed early for attribute resolution
   • The assembly content (toc and abstract) correctly precedes module includes
   • Consider adjusting the Vale rule to allow content after common-attributes includes but before module includes

Module Structure Analysis

All included modules (delete-acs-namespace.adoc, delete-acs-global-resources.adoc, delete-acs-label-annotation.adoc) are properly structured with:

• ✓ Content type attributes (:_mod-docs-content-type: PROCEDURE)
• ✓ Contextual IDs ([id=".._{context}"])
• ✓ Abstract paragraphs ([role="_abstract"])
• ✓ Proper procedure formatting

Assembly Structure

The assembly follows this structure (which is DITA-compatible):

:_mod-docs-content-type: ASSEMBLY        ← Assembly metadata
[id="uninstall-acs"]                     ← Assembly ID
= Title                                  ← Assembly title
include::modules/common-attributes.adoc[]← Attribute definitions (special case)
:context: uninstall-acs                  ← Context setting

toc::[]                                  ← Table of contents

[role="_abstract"]                       ← Abstract paragraph
<assembly introduction content>

include::modules/...                     ← Module includes
include::modules/...
include::modules/...

This structure is standard and acceptable for AsciiDoc assemblies intended for DITA conversion.

Test Plan

If changes were to be applied:

• Verify the AsciiDoc renders correctly
• Run DITA conversion on the assembly
• Confirm all attributes resolve correctly
• Verify table of contents generates properly
• Check that abstract paragraph displays correctly

Dry-Run Conclusion

No changes recommended. The 2 Vale issues identified appear to be:

• 1 false positive (AuthorLine rule incorrectly flagging a common-attributes include)
• 1 acceptable pattern (AssemblyContents rule not accounting for common-attributes include special case)

The assembly and its included modules are already well-structured for DITA conversion. The Vale rules may need adjustment to account for common AsciiDoc assembly patterns.

---

Generated with AI Code Tools (Dry-Run Mode)

[ocpdocs-previewbot]

🤖 Fri May 08 08:36:43 - Prow CI generated the docs preview:

https://111418--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/uninstall-acs.html

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

[agantony]

📝 Changes Summary

This PR fixes Vale style guide compliance issues with minimal changes to improve grammar and voice:

Files Modified (2)

File	Lines Changed	Type of Change
installing/uninstall-acs.adoc	1	Passive → Active voice
modules/delete-acs-global-resources.adoc	3	Whitespace fix + Passive → Active voice

Key Changes

✅ Line 12 (installing/uninstall-acs.adoc):

• Changed "where the Operator is installed" → "where you install the Operator"
• Improves clarity by using active voice

✅ Line 17 (modules/delete-acs-global-resources.adoc):

• Removed trailing space from continuation marker

✅ Lines 24 & 54 (modules/delete-acs-global-resources.adoc):

• Changed "The PSPs were removed" → "Kubernetes removed the PSPs"
• Improves clarity and removes passive voice

🔗 Preview Link

📄 View the uninstall page preview

All changes are visible on this single page since the module is included in the assembly.

✅ Status

• All CI checks passed
• Vale errors resolved
• Ready for review