WMCO remove [discrete] tags in prep for DITA migration

[mburke5678]

Demoting instances of == Prerequisites to .Prerequisites and removing the associated [discrete] tag to prep for DITA migration. See #96676

Previews
Creating a Windows machine set on AWS
Creating a Windows machine set on Azure
Creating a Windows machine set on GCP
Creating a Windows MachineSet object on Nutanix
Creating a Windows machine set on vSphere
Disabling Windows container workloads
Enabling Windows container workloads
Scheduling Windows container workloads

[mburke5678]

@bergerhoffer Does this meet your expectations?

[mburke5678]

/retest

[ocpdocs-previewbot]

🤖 Mon Jul 28 15:07:10 - Prow CI generated the docs preview:

https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.html
https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/creating_windows_machinesets/creating-windows-machineset-azure.html
https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/creating_windows_machinesets/creating-windows-machineset-gcp.html
https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/creating_windows_machinesets/creating-windows-machineset-nutanix.html
https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.html
https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/disabling-windows-container-workloads.html
https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/enabling-windows-container-workloads.html
https://96757--ocpdocs-pr.netlify.app/openshift-enterprise/latest/windows_containers/scheduling-windows-workloads.html

[openshift-ci]

@mburke5678: all tests passed!

Full PR test history. Your PR dashboard.

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.

[bergerhoffer]

@bergerhoffer Does this meet your expectations?

Let me double check w/ the ToolX team that there isn't an issue with these .Titles being in assemblies before I ack it.

[jhradilek]

Hi @mburke5678, you can and should use the AsciiDocDITA Vale style to verify that the changes you make actually help prepare the modules and assemblies for DITA migration. This has been recommended on multiple calls, is more accurate than arbitrary sed and grep commands, and can prevent situations like this where people make changes that do not actually prepare the content for DITA migration as intended.

In this situation, replacing a discrete heading with a block title replaces one problem with another as outside of procedures, where select few documented block titles are used to map content to correct DITA elements allowed in <taskbody>, titles can only be assigned to tables, explicit example blocks, and images. There is no way in DITA to assign a title to an unordered list, which is what the block title is doing.

If you insist on having prerequisites in the assembly, which is not the correct approach in DITA, just remove the [descrete] attribute list and keep the prerequisites as a level 1 section (==). The correct way would be to move the prerequisites to the modules themselves, as that way you can guarantee they can be reasonably reused.

[mburke5678]

@jhradilek Can you explain this to me?

The correct way would be to move the prerequisites to the modules themselves,

That doesn't make sense to me right off. Would you have a snippet module for each set of prerequisites?

What if we change the =Prerequisites to bold text?

[bergerhoffer]

@mburke5678 I got more detail from Jaromir today (as a preview of the preparing for migration session tomorrow).

Apparently block titles are NOT able to be used on pretty much anything except in procedure modules as the .Prerequisites / .Procedure, etc. items. (And a few other items like a table, example, or figure). So, not even on lists in assemblies or concept or reference modules.

Per the assembly template: https://raw.githubusercontent.com/redhat-documentation/modular-docs/refs/heads/main/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc

They do have == Prerequisites as a level 2 (==) heading that appears in the TOC. So I think the right answer for your content here is to remove the discrete headings (you can let it happen in my PR) and let it appear in the TOC. It's an assembly-wide prereq section, so I think it makes sense to appear in the TOC.

(And bold text isn't really a heading, so that's not really the right change here).

So my recommendation is to just close this PR and let my PR handle removing the discrete tags.

[mburke5678]

@bergerhoffer Thank you for your helpful comment. I am closing this PR. All yours!