Skip to content

AAP-49039: Made edits per Dita premigration checks for Lightspeed chatbot #3772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

sayjadha
Copy link
Contributor

@sayjadha sayjadha commented Jul 3, 2025

This PR addresses JIRA https://issues.redhat.com/browse/AAP-49038.

Changes made:

  • Dita premigration check and creating separate procedure files for:
    proc-install-aap-operator-chatbot.adoc | aap-operator-installation | Sections in procedure modules
  • Other minor heading-level changes.

= Configuring the {PlatformNameShort} operator
After installing the {OperatorPlatformNameShort} in your namespace, configure the {PlatformNameShort} operator to link your components to the {Gateway}.

include::proc-operator-link-components.adoc[leveloffset=+2]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey Sayee, this is what's causing the the warning message. It's not build breaking but it is an issue for a few reasons:

  • The warning is saying that it expects the level offset to be 1 here not two, however it's pushing the headings beyond a H3 which the Toolx team say we can't do.
  • We're currently nesting a procedure within another procedure, which might cause issues with DITA. According to our modular documentation guidelines, procedures should ideally be standalone or integrated into an assembly.
  • I'm also a bit unsure about including full steps within the Verification section. My understanding is that verification steps should primarily confirm the outcome, rather than outline new actions, but I could be mistaken here.
  • Finally, those extra verification steps, while looking good now, could potentially lead to misalignment if proc-operator-link-components.adoc changes in the future (e.g., if additional resources are added).

Here is a refresher on the Migration checklist

And here's the mod docs guide

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @g-murray , thank you for the review. Here are a few comments:

  • Changed include::proc-operator-link-components.adoc from leveloffset=2 to leveloffset=1 and I no longer see a build error so looks like we're good here.

  • W.r.t. verification steps, I was looking through the Mod Docs guide and came across this discussion:
    Clarification required regarding numbered lists redhat-documentation/modular-docs#138 -> https://redhat-documentation.github.io/supplementary-style-guide/#_principle_5_error_recovery_verification_and_troubleshooting. Looks like verification can have steps, and could be better suited in this case, where to verify an outcome, the user has to follow a particular sequence on the UI to get to the correct page. I'm retaining the current text as is until this gets reported by the migration team.

  • The verification steps will not change if additional resources are added to proc-operator-link-components.adoc. The verification requires users to confirm that their installation is completed successfully, with no component displaying any errors. Also, these are the steps to view the installation status. Again, not making any change here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants