RHIDP-6146: Create developer-focused TechDocs content

[linfraze]

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

Version(s):
1.6
Issue:
https://issues.redhat.com/browse/RHIDP-6146
Preview:
https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1082/techdocs/#assembly-using-techdocs

[rhdh-bot]

Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1082/ @ 04/30/25 20:19:13

[benwilcock]

In 3.1.1 what about the case where a user wants to add techdocs via a reference to an existing catalog-info.yaml (the docs with your code approach)? In this scenario the docs and the code would be in the same repo and the catalog-info.yaml would be used to refer to the docs. The docs would then be registered automatically and ingested as part of the usual code ingestion process.

[linfraze]

@AndrienkoAleksandr as part of the tech review, can you please help me address Ben's comment? TBH, I'm not sure what needs to be changed or added to cover that use case, since we already explain that the docs and code are in the same repo and walk the user through how to import docs with the catalog-info.yaml, so I might be missing something. Thanks!

In 3.1.1 what about the case where a user wants to add techdocs via a reference to an existing catalog-info.yaml (the docs with your code approach)? In this scenario the docs and the code would be in the same repo and the catalog-info.yaml would be used to refer to the docs. The docs would then be registered automatically and ingested as part of the usual code ingestion process.

[PatAKnight]

@linfraze What I believe @benwilcock is mentioning is the scenario where tech docs are added after the fact. This would require the user to update the catalog-info.yaml file to point to the newly added documentation. So the steps and prereqs would be something like the following:

prereqs:

• Catalog entity already present in the catalog with no documentation
• Access to the repo in which the catalog entity lives

1. Create the documentation that you wish to include in RHDH

2. Create the mkdocs.yaml file

3. Update the catalog-info.yaml file to reference the mkdocs.yaml file

   What the update would potentially look like:

   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: some-component
     title: Some Component
     annotations:
       # this could also be `url:<url>` if the documentation isn't in the same location
       backstage.io/techdocs-ref: dir:. # Added after the entity has been registered
   

   Link for reference: https://backstage.io/docs/features/techdocs/creating-and-publishing#create-a-standalone-documentation

4. Either trigger a resync (if the user has the appropriate permissions) or wait for the update to the catalog entity to be picked up by RHDH

Edit: Literally just stumbled upon this exact scenario here in the Backstage docs: https://backstage.io/docs/features/techdocs/creating-and-publishing#enable-documentation-for-an-already-existing-entity

Edit 2: permissions for syncing catalog.entity.refresh.

[PatAKnight]

Looks pretty good to me

[linfraze]

@benwilcock other Adding documentation to TechDocs use cases require the user to register a component in the software catalog. The upstream docs cover multiple ways to do this:

• Manually register components
• Creating new components through [RHDH]
• Integrating with an external source

Are all of these options supported in RHDH? Is there a primary / preferred way that we want to provide enterprise docs for?

NOTE: Some use cases that we haven't yet covered open a bit of a rabbit hole, as they also require us to document prerequisite and tangential procedures that require the docs team to engage in deeper stakeholder conversations and Q&A. Given our timeline for 1.6, we will likely need to doc add'l use cases post-GA.

[hmanwani-rh]

/cherry-pick release-1.6

[openshift-cherrypick-robot]

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

In response to this:

/cherry-pick release-1.6

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.