RHIDP-5422: TechDocs add-ons doc

[linfraze]

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s):
1.5

Issue:
https://issues.redhat.com/browse/RHIDP-5422

Preview:
https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-975/techdocs/

[rhdh-bot]

Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-975/ @ 03/24/25 14:10:53

[hmanwani-rh]

/cherry-pick release-1.5

[openshift-cherrypick-robot]

@hmanwani-rh: once the present PR merges, I will cherry-pick it on top of release-1.5 in a new PR and assign it to you.

In response to this:

/cherry-pick release-1.5

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]

@hmanwani-rh: new pull request created: #1016

In response to this:

/cherry-pick release-1.5

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.

[dzemanov]

Suggested change

TechDocs add-ons are supported by {company-name} are imported by the `backstage-plugin-techdocs-module-addons-contrib` plugin package. The `<ReportIssue />` add-on is preinstalled in the TechDocs plugin and enabled by default. You can install external TechDocs add-ons by adding them to `backstage-plugin-techdocs-module-addons-contrib` package with either the {product} Operator or Helm chart. Additionally, you can import compatible third-party add-ons, including add-ons that you create yourself, with a third-party dynamic plugin.

TechDocs add-ons supported by {company-name} come from preinstalled external plugin package `backstage-plugin-techdocs-module-addons-contrib`. The `<ReportIssue />` add-on from this plugin package is preconfigured and enabled by the default to be used by the TechDocs plugin. You can configure other external TechDocs add-ons from `backstage-plugin-techdocs-module-addons-contrib` plugin package by configuring the {product} Operator or Helm chart. Additionally, you can install third-party add-ons, including add-ons that you create yourself, by installing a third-party dynamic plugin that exports them.

[linfraze]

@dzemanov I submitted a new PR to update this paragraph: #1026 please review when you get a chance.

As you review the updates, please keep in mind that we are currently using the terms install, preinstalled, external, ConfigMap throughout the doc and I'm striving to align with that language in this paragraph. If changing the language would improve the technical accuracy and clarity of the content, then we need to address that globally (under a separate ticket) and not just in this one paragraph. In other words, maybe Installing TechDocs add-ons by using the Operator is not the most accurate or clear language to describe what the user is actually doing to make TextSize or LightBox work in their TechDocs plugin - if that's the case, those terms will need to be changed in that title and throughout the entire doc.

But I also have some Qs:

• What do we mean by "come from" here -- what is technically happening here, if not "import"? Are we exporting them to the TechDocs plugin from the contrib package?
• Is it possible to have an existing third-party plugin already installed that you want to use to export a third-party add-on?
• Is the user actually configuring the Operator? Or the ConfigMap?

[dzemanov]

@linfraze you are right Lindsey, we are using these terms throughout the Techdocs documentation and there are other parts that will need to be renamed / restructured besides this paragraph. I think we should rather use term enabling for the add-ons from contrib package as this package is preinstalled on RHDH, with ReportIssue add-on being preconfigured and so enabled by default. We still need the installing part for Helm and Operator for the third party add-ons. Of course, users can also override the default configuration and disable this contrib package so then it will not be installed and no add-ons will be used from this plugin.

What do we mean by "come from" here -- what is technically happening here, if not "import"? Are we exporting them to the TechDocs plugin from the contrib package?

Yes, that is what we are doing. The contrib package is exporting Techdocs add-ons, see here. It already contains the add-ons. That is why i want to avoid the phrasing "add-ons ... are imported by the backstage-plugin-techdocs-module-addons-contrib plugin package."

The import part:
On the other side, we have our Backstage app, that is importing these add-ons from plugins (like contrib plugin or any external plugin) and we are providing configuration per package (plugin) that contains these add-ons so they can be rendered in the correct place.

Is it possible to have an existing third-party plugin already installed that you want to use to export a third-party add-on?

Yes, you can. You would need to publish new version of your plugin that would contain (and export) the add-on and you would need to then use that version of the plugin and also specify the configuration with techDocsAddons: ... for that plugin.
But usually you would create a separate plugin for your add-ons. I do not think this needs to be explicitly mentioned in the documentation.

Is the user actually configuring the Operator? Or the ConfigMap?
The administrator needs to configure ConfigMap. For add-ons from contrib package, if users want more than ReportIssue, then dynamic-plugins-rhdh ConfigMap needs to be updated with:

      - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
        disabled: false
        pluginConfig:
          dynamicPlugins:
            frontend:
              backstage.plugin-techdocs-module-addons-contrib:
                techdocsAddons:
                  - importName: ReportIssue
                  - importName: TextSize
                  - importName: LightBox

(For all add-ons).

[dzemanov]

This can be confusing, but actually enabling a plugin doesn't automatically enable all add-ons that are part of that plugin. One needs to configure them via configuration that was shown here. If one disables the plugin itself, then yes, all the add-ons are disabled. But it doesn't go the other way around.

[linfraze]

I see what you mean. I think we should remove the information about enabling, especially since the plugin package is enabled by default and we talk about how to disable in the Removing section. If a user understands how to disable, then the concepts and procedures for re-enabling are obvious.