Removing [discrete] tags from main in prep for DITA migration #96676

bergerhoffer · 2025-07-24T15:18:40Z

Version(s):
4.14+. Will CP back as far as I can, and then run additional removals as necessary in future PRs.

Issue:
https://issues.redhat.com/browse/OSDOCS-15507

Link to docs preview:

QE review:
N/A - formatting only change

Additional information:

Marking [WIP] because we want to notify the core team and aligned teams of this, in case they want to make any changes to any of their content.

Also want to see if this will break anything :) For example, some headings don't have IDs specified - not sure if that will cause any grief.

Editing to add that the build failed due to some of the headings being out of order. Opened https://issues.redhat.com/browse/OSDOCS-15521 to address those first before doing the removal sweep

ocpdocs-previewbot · 2025-07-24T15:41:56Z

🤖 Thu Sep 11 16:55:43 - Prow CI generated the docs preview:
https://96676--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

bergerhoffer · 2025-07-24T22:19:29Z

On hold until the build errors are fixed. Being done by https://issues.redhat.com/browse/OSDOCS-15521.

mburke5678 · 2025-07-28T13:30:34Z

Node, MCO LGTM
Windows, several Prerequisite heading that can be demoted.

networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc

jeana-redhat

Changes in my topic areas LGTM. I had some Qs/comments on cluster Operators and capabilities content.

jeana-redhat · 2025-07-28T13:25:54Z

operators/operator-reference.adoc

This seems like one of the weirder areas for this change - because of how the Operator entries are organized, it will really explode the TOC

Existing: https://docs.okd.io/latest/operators/operator-reference.html
Updated: https://96676--ocpdocs-pr.netlify.app/openshift-enterprise/latest/operators/operator-reference

I see there is an Operators ref specific PR up here, is the intent to ditch this change in here and use that?

That version: https://96711--ocpdocs-pr.netlify.app/openshift-enterprise/latest/operators/operator-reference

It still has what seem like pretty low-value headings bogging down the TOC. I would consider looking at using description lists for all the == headings in the cluster Operator modules, imho they don't really need to be headings.

Cc @abrennan89 @michaelryanpeter

This seems like one of the weirder areas for this change - because of how the Operator entries are organized, it will really explode the TOC

Existing: https://docs.okd.io/latest/operators/operator-reference.html Updated: https://96676--ocpdocs-pr.netlify.app/openshift-enterprise/latest/operators/operator-reference

I see there is an Operators ref specific PR up here, is the intent to ditch this change in here and use that?

That version: https://96711--ocpdocs-pr.netlify.app/openshift-enterprise/latest/operators/operator-reference

It still has what seem like pretty low-value headings bogging down the TOC. I would consider looking at using description lists for all the == headings in the cluster Operator modules, imho they don't really need to be headings.

Cc @abrennan89 @michaelryanpeter

Consider level 3 headings as well. I don't think these show in TOCs.

Level 3 headings are also on the list of cleanup items, we will only be able to go as deep as level 2 going forward

Rock and a hard place 🪨 . Description lists might be the best path forward 👍 .

Should we move this discussion to the appropriate PR?

To recap the other PR:

Ashleigh is going to remove the Purpose headings

I'll create a follow up PR once her PR merges to move the Project content to the trailing additional resources sections and move any Notes to the main body text.

That leaves CRD and Configuration headings behind. Though that content is skeletal, it is at least information customers will be scanning for.

jeana-redhat · 2025-07-28T13:38:20Z

modules/machine-api-capability.adoc

The modules in the installing/overview/cluster-capabilities.adoc assembly have a similar format as the ones in the cluster Operator modules: https://96676--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/overview/cluster-capabilities#machine-api-capability_cluster-capabilities

They don't explode the TOC because they are nested one level deeper, but I feel like maybe they also might make sense as description lists because the headings are sorta low-value?

Oops, should have Cc'ed @bscott-rh here

JoeAldinger · 2025-07-28T17:21:24Z

nwt, lgtm.

bergerhoffer · 2025-09-09T20:27:18Z

I've updated this to do a fresh removal, but not to include aligned team files (where possible to identify them easily).

bergerhoffer · 2025-09-11T16:46:26Z

/retest

openshift-ci · 2025-09-11T17:05:47Z

@bergerhoffer: 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 · 2025-09-11T18:59:42Z

/cherrypick enterprise-4.20

bergerhoffer · 2025-09-11T18:59:46Z

/cherrypick enterprise-4.19

bergerhoffer · 2025-09-11T18:59:51Z

/cherrypick enterprise-4.18

openshift-cherrypick-robot · 2025-09-11T19:00:27Z

@bergerhoffer: #96676 failed to apply on top of branch "enterprise-4.20":

Applying: OSDOCS#15507: Removing discrete headings in core OCP docs
Using index info to reconstruct a base tree...
M	migrating_from_ocp_3_to_4/planning-migration-3-4.adoc
M	modules/cluster-image-registry-operator.adoc
M	modules/coreos-layering-configuring-on.adoc
M	modules/ingress-operator.adoc
M	modules/installation-vsphere-installer-infra-requirements.adoc
M	modules/nw-egress-ips-about.adoc
M	security/certificate_types_descriptions/service-ca-certificates.adoc
M	welcome/learn_more_about_openshift.adoc
Falling back to patching base and 3-way merge...
Auto-merging welcome/learn_more_about_openshift.adoc
CONFLICT (content): Merge conflict in welcome/learn_more_about_openshift.adoc
Auto-merging security/certificate_types_descriptions/service-ca-certificates.adoc
Auto-merging modules/nw-egress-ips-about.adoc
Auto-merging modules/installation-vsphere-installer-infra-requirements.adoc
Auto-merging modules/ingress-operator.adoc
Auto-merging modules/coreos-layering-configuring-on.adoc
Auto-merging modules/cluster-image-registry-operator.adoc
Auto-merging migrating_from_ocp_3_to_4/planning-migration-3-4.adoc
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config advice.mergeConflict false"
Patch failed at 0001 OSDOCS#15507: Removing discrete headings in core OCP docs

In response to this:

/cherrypick enterprise-4.20

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.

openshift-cherrypick-robot · 2025-09-11T19:00:29Z

@bergerhoffer: #96676 failed to apply on top of branch "enterprise-4.19":

Applying: OSDOCS#15507: Removing discrete headings in core OCP docs
Using index info to reconstruct a base tree...
M	migrating_from_ocp_3_to_4/planning-migration-3-4.adoc
M	modules/cli-installing-cli.adoc
M	modules/cluster-image-registry-operator.adoc
M	modules/coreos-layering-configuring-on.adoc
M	modules/ingress-operator.adoc
M	modules/installation-custom-aws-vpc.adoc
M	modules/nw-egress-ips-about.adoc
M	modules/nw-operator-cr.adoc
M	rest_api/objects/index.adoc
M	security/certificate_types_descriptions/service-ca-certificates.adoc
M	windows_containers/enabling-windows-container-workloads.adoc
Falling back to patching base and 3-way merge...
Auto-merging windows_containers/enabling-windows-container-workloads.adoc
Auto-merging security/certificate_types_descriptions/service-ca-certificates.adoc
Auto-merging rest_api/objects/index.adoc
CONFLICT (content): Merge conflict in rest_api/objects/index.adoc
Auto-merging modules/nw-operator-cr.adoc
Auto-merging modules/nw-egress-ips-about.adoc
Auto-merging modules/installation-custom-aws-vpc.adoc
Auto-merging modules/ingress-operator.adoc
Auto-merging modules/coreos-layering-configuring-on.adoc
Auto-merging modules/cluster-image-registry-operator.adoc
Auto-merging modules/cli-installing-cli.adoc
Auto-merging migrating_from_ocp_3_to_4/planning-migration-3-4.adoc
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config advice.mergeConflict false"
Patch failed at 0001 OSDOCS#15507: Removing discrete headings in core OCP docs

In response to this:

/cherrypick enterprise-4.19

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.

openshift-cherrypick-robot · 2025-09-11T19:00:34Z

@bergerhoffer: #96676 failed to apply on top of branch "enterprise-4.18":

Applying: OSDOCS#15507: Removing discrete headings in core OCP docs
Using index info to reconstruct a base tree...
M	architecture/architecture-installation.adoc
M	hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc
M	installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc
M	installing/overview/index.adoc
M	machine_management/creating_machinesets/creating-machineset-vsphere.adoc
M	migrating_from_ocp_3_to_4/planning-migration-3-4.adoc
M	modules/application-health-about.adoc
M	modules/cli-installing-cli.adoc
M	modules/cluster-capi-operator.adoc
M	modules/cluster-image-registry-operator.adoc
M	modules/cluster-wide-proxy-preqs.adoc
M	modules/coreos-layering-configuring-on.adoc
M	modules/dynamic-plugin-api.adoc
M	modules/dynamic-plugin-sdk-extensions.adoc
M	modules/how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects.adoc
M	modules/installation-custom-aws-vpc.adoc
M	modules/ipi-install-additional-install-config-parameters.adoc
M	modules/minimum-ibm-power-system-requirements.adoc
M	modules/nw-egress-ips-about.adoc
M	modules/nw-infw-operator-config-object.adoc
M	modules/nw-operator-cr.adoc
M	modules/nw-ovn-kubernetes-session-affinity.adoc
M	modules/oc-mirror-image-set-config-examples.adoc
A	modules/understand-etcd-performance.adoc
M	networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc
M	networking/networking_overview/about-managed-networking.adoc
M	openshift_images/configuring-samples-operator.adoc
M	operators/operator-reference.adoc
M	rest_api/objects/index.adoc
M	scalability_and_performance/index.adoc
M	security/certificate_types_descriptions/service-ca-certificates.adoc
M	security/index.adoc
M	snippets/vpc-troubleshooting.adoc
M	web_console/dynamic-plugin/overview-dynamic-plugin.adoc
M	web_console/web_terminal/installing-web-terminal.adoc
M	welcome/learn_more_about_openshift.adoc
M	windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc
M	windows_containers/enabling-windows-container-workloads.adoc
Falling back to patching base and 3-way merge...
Auto-merging windows_containers/enabling-windows-container-workloads.adoc
Auto-merging windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc
Auto-merging welcome/learn_more_about_openshift.adoc
Auto-merging web_console/web_terminal/installing-web-terminal.adoc
Auto-merging web_console/dynamic-plugin/overview-dynamic-plugin.adoc
Auto-merging snippets/vpc-troubleshooting.adoc
Auto-merging security/index.adoc
Auto-merging security/certificate_types_descriptions/service-ca-certificates.adoc
Auto-merging scalability_and_performance/index.adoc
CONFLICT (content): Merge conflict in scalability_and_performance/index.adoc
Auto-merging rest_api/objects/index.adoc
CONFLICT (content): Merge conflict in rest_api/objects/index.adoc
Auto-merging operators/operator-reference.adoc
Auto-merging openshift_images/configuring-samples-operator.adoc
Auto-merging networking/networking_overview/about-managed-networking.adoc
Auto-merging networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc
CONFLICT (modify/delete): modules/understand-etcd-performance.adoc deleted in HEAD and modified in OSDOCS#15507: Removing discrete headings in core OCP docs. Version OSDOCS#15507: Removing discrete headings in core OCP docs of modules/understand-etcd-performance.adoc left in tree.
Auto-merging modules/oc-mirror-image-set-config-examples.adoc
Auto-merging modules/nw-ovn-kubernetes-session-affinity.adoc
Auto-merging modules/nw-operator-cr.adoc
Auto-merging modules/nw-infw-operator-config-object.adoc
CONFLICT (content): Merge conflict in modules/nw-infw-operator-config-object.adoc
Auto-merging modules/nw-egress-ips-about.adoc
Auto-merging modules/minimum-ibm-power-system-requirements.adoc
Auto-merging modules/ipi-install-additional-install-config-parameters.adoc
Auto-merging modules/installation-custom-aws-vpc.adoc
Auto-merging modules/how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects.adoc
Auto-merging modules/dynamic-plugin-sdk-extensions.adoc
Auto-merging modules/dynamic-plugin-api.adoc
CONFLICT (content): Merge conflict in modules/dynamic-plugin-api.adoc
Auto-merging modules/coreos-layering-configuring-on.adoc
Auto-merging modules/cluster-wide-proxy-preqs.adoc
Auto-merging modules/cluster-image-registry-operator.adoc
Auto-merging modules/cluster-capi-operator.adoc
Auto-merging modules/cli-installing-cli.adoc
Auto-merging modules/application-health-about.adoc
Auto-merging migrating_from_ocp_3_to_4/planning-migration-3-4.adoc
CONFLICT (content): Merge conflict in migrating_from_ocp_3_to_4/planning-migration-3-4.adoc
Auto-merging machine_management/creating_machinesets/creating-machineset-vsphere.adoc
Auto-merging installing/overview/index.adoc
Auto-merging installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc
Auto-merging hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc
CONFLICT (content): Merge conflict in hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc
Auto-merging architecture/architecture-installation.adoc
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config advice.mergeConflict false"
Patch failed at 0001 OSDOCS#15507: Removing discrete headings in core OCP docs

In response to this:

/cherrypick enterprise-4.18

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.

openshift-ci bot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Jul 24, 2025

bergerhoffer force-pushed the OSDOCS-15507-main branch 3 times, most recently from c84090f to f30fb46 Compare July 24, 2025 17:28

bergerhoffer changed the title ~~[WIP] Removing [disrete] tags from main in prep for DITA migration~~ [WIP] Removing [discrete] tags from main in prep for DITA migration Jul 24, 2025

dfitzmau reviewed Jul 28, 2025

View reviewed changes

networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc Show resolved Hide resolved

mburke5678 mentioned this pull request Jul 28, 2025

WMCO remove [discrete] tags in prep for DITA migration #96757

Closed

jeana-redhat reviewed Jul 28, 2025

View reviewed changes

ShaunaDiaz mentioned this pull request Jul 29, 2025

OSDOCS-15507-ms: removes discrete headings API docs MicroShift #96789

Merged

jeana-redhat mentioned this pull request Jul 29, 2025

OSDOCS-15521: Remove unnecessary headings and fix ID for Operator ref doc #96711

Merged

gwynnemonahan mentioned this pull request Jul 29, 2025

POWERMON-579 Visualizing power monitoring metrics doc updates #95534

Merged

1 task

openshift-merge-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 3, 2025

mburke5678 mentioned this pull request Aug 6, 2025

[OSDOCS-15316]: Revising formatting in HCP bare metal docs #97184

Merged

bergerhoffer force-pushed the OSDOCS-15507-main branch 2 times, most recently from 891cfc7 to e9cd75a Compare September 9, 2025 19:49

openshift-merge-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 9, 2025

bergerhoffer changed the title ~~[WIP] Removing [discrete] tags from main in prep for DITA migration~~ Removing [discrete] tags from main in prep for DITA migration Sep 11, 2025

openshift-ci bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Sep 11, 2025

OSDOCS#15507: Removing discrete headings in core OCP docs

aa9e9c9

bergerhoffer force-pushed the OSDOCS-15507-main branch from e9cd75a to aa9e9c9 Compare September 11, 2025 16:11

bergerhoffer merged commit dd239ac into openshift:main Sep 11, 2025
2 checks passed

bergerhoffer added branch/enterprise-4.14 branch/enterprise-4.15 branch/enterprise-4.16 branch/enterprise-4.17 branch/enterprise-4.18 branch/enterprise-4.19 branch/enterprise-4.20 labels Sep 11, 2025

Removing [discrete] tags from main in prep for DITA migration #96676

Removing [discrete] tags from main in prep for DITA migration #96676

Uh oh!

Conversation

bergerhoffer commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bergerhoffer commented Jul 24, 2025

Uh oh!

mburke5678 commented Jul 28, 2025

Uh oh!

Uh oh!

jeana-redhat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JoeAldinger commented Jul 28, 2025

Uh oh!

bergerhoffer commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bergerhoffer commented Sep 11, 2025

Uh oh!

openshift-ci bot commented Sep 11, 2025

Uh oh!

Uh oh!

bergerhoffer commented Sep 11, 2025

Uh oh!

bergerhoffer commented Sep 11, 2025

Uh oh!

bergerhoffer commented Sep 11, 2025

Uh oh!

openshift-cherrypick-robot commented Sep 11, 2025

Uh oh!

openshift-cherrypick-robot commented Sep 11, 2025

Uh oh!

openshift-cherrypick-robot commented Sep 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

bergerhoffer commented Jul 24, 2025 •

edited

Loading

ocpdocs-previewbot commented Jul 24, 2025 •

edited

Loading

bergerhoffer commented Sep 9, 2025 •

edited

Loading