structure: topic map please confirm title guidance

[sean-freeman]

structure: topic map please confirm title guidance

@kalexand-rh @bscott-rh @sheriff-rh @sstout-rh

Ahead of raising a PR which will include topic map consistency changes and appending subdirectory structure (preparation prior to subsequent PR with new content), I need to be clear on what the guidance/rules actually are.

Particularly as my last PRs were rejected, and yet an accepted PR #83982 did not comply with what had been described to me:

2024-10-24: ' The decision was made during the 4.16 reorgs to remove "with installer-provisioned infrastructure" and "with user-provisioned infrastructure" from the Topic Map assembly titles to improve readability. '
Ref: #83386 (comment)

2024-10-29 ' The phrase "with installer-provisioned infrastructure" and "with user-provisioned infrastructure" is being removed from the topic map (left hand TOC) assembly titles, but the headings inside the actual assemblies can still have that phrase for SEO reasons. Note that the full phrase should be used, not the acronym "UPI" or "IPI". '
Ref: #83386 (comment)

Please scroll through sections below.

At the end, I suggest structured guidance that can be followed by those raising 'cleanup PRs' such as myself.

---

Topic map reference structure

• Topic: Installing on TARGET
  • Sub-Topic: Installer-provisioned infrastructure
    • <Topic Title> linked to <Filename>, which contains <Assembly Heading>
  • Sub-Topic: User-provisioned infrastructure
    • <Topic Title> linked to <Filename>, which contains <Assembly Heading>

Current topic map and assembly titles

• Installing on TARGET
  • Installer-provisioned infrastructure
    • N/A, no use of Installer-provisioned / IPI in Topic Map titles
  • User-provisioned infrastructure
    • Installing a cluster in a disconnected environment with user-provisioned infrastructure

Examples in Topic Map:

- Name: Installing on AWS
  Topics:
  - Name: Installer-provisioned infrastructure
    Dir: ipi
  - Name: User-provisioned infrastructure
    Dir: upi
    Topics:
    ....
    - Name: Installing a cluster in a disconnected environment with user-provisioned infrastructure
      File: installing-restricted-networks-aws

- Name: Installing on Azure

  Topics:
  - Name: Installer-provisioned infrastructure
    Dir: ipi
  - Name: User-provisioned infrastructure
    Dir: upi
    Topics:
    ....
    - Name: Installing a cluster in a disconnected environment with user-provisioned infrastructure

- Name: Installing on GCP
  Dir: installing_gcp
  Topics:
  - Name: Installing a cluster on GCP in a disconnected environment with user-provisioned infrastructure

- Name: Installing on bare metal
  Dir: installing_bare_metal
  Topics:
  - Name: Installer-provisioned infrastructure
    Dir: ipi
  - Name: User-provisioned infrastructure
    Dir: upi
    Topics:
    ....
    - Name: Installing a user-provisioned cluster on bare metal
    - Name: Installing a user-provisioned bare metal cluster with network customizations
    - Name: Installing a user-provisioned bare metal cluster on a disconnected environment
    - Name: Scaling a user-provisioned installation with the bare metal operator

Examples in Assembly Headings differing from Topic Map Titles (slightly):

:_mod-docs-content-type: ASSEMBLY
[id="installing-restricted-networks-aws"]
= Installing a cluster on AWS in a disconnected environment with user-provisioned infrastructure
include::_attributes/common-attributes.adoc[]
:context: installing-restricted-networks-aws

:_mod-docs-content-type: ASSEMBLY
[id="installing-restricted-networks-azure-user-provisioned"]
= Installing a cluster on Azure in a disconnected environment with user-provisioned infrastructure
include::_attributes/common-attributes.adoc[]
:context: installing-restricted-networks-azure-user-provisioned

:_mod-docs-content-type: ASSEMBLY
[id="scaling-a-user-provisioned-cluster-with-the-bare-metal-operator"]
= Scaling a user-provisioned cluster with the Bare Metal Operator
include::_attributes/common-attributes.adoc[]
:context: scaling-a-user-provisioned-cluster-with-the-bare-metal-operator

---

Suggested guidance

The Topic Map contains many Topics, which can be nested. For example, the Installing Topic will contain various Installing on TARGET PLATFORM Sub-Topics - and within the specific platform (e.g. AWS), there would be different types of installation.

When collpased, this would look like:

Name: Installing
Dir: installing
Topics:
- Name: Installing on AWS
  Dir: installing_aws
  Topics:
  - Name: Installation methods
  - Name: Installer-provisioned infrastructure
    Dir: ipi

For navigation purposes, it is important that the Topic Map contains Titles which are succinct and consistent with what is shown in the Product / Marketing.

The Topic Map refers to the specific content file, and this will contain an Assembly Heading. This provides consistency across all target platforms, while allowing improved SEO of the more verbose Assembly Heading.

Example is shown below.

Topic Map Titles:

• Installing
  • Installing on Bare Metal
    • Installing a cluster on bare metal with Interactive Assisted Installer
    • Installing a cluster on bare metal with Local Agent-based Assisted Installer
    • Installing a cluster on bare metal with Automated (IPI) Installer
    • Installing a cluster on bare metal with Full Control (UPI) Installer

Assembly Headings:

:_mod-docs-content-type: ASSEMBLY
= Installing a cluster on bare metal with Automated Installer-Provisioned Infrastructure and network customizations

NOTE: Migration is required for previous terms used in documentation:

Location	Before	After
Topic Map Title	Installer-provisioned infrastructure	Automated (IPI) Installer
Topic Map Title	User-provisioned infrastructure	Full Control (UPI) Installer
-	-	-
Assembly Heading	Assisted install cluster	Interactive Assisted installed cluster
Assembly Heading	Agent-based install cluster	Local Agent installed cluster
Assembly Heading	IPI cluster	Automated IPI installed cluster
Assembly Heading	UPI cluster	Full Control UPI installed cluster