[release-1.6] RHIDP-6145: Added developer-focused content for software templates (#1164)

openshift-cherrypick-robot · pabel-rh · web-flow · commit 5a6789c1114a · 2025-05-14T16:17:15.000+05:30
* Added software templates content

* Incorporate Lindsey's comments

* Added additional resource

* Made changes

* Fixing broken link

* Updated intro

* Updated screenshot

* Incorporated minor change

* Added screenshot

* Incorporated Debsmita's comments

* Minor change

---------

Co-authored-by: Priyanka Abel &lt;pabel@redhat.com&gt;
diff --git a/assemblies/assembly-configuring-templates.adoc b/assemblies/assembly-configuring-templates.adoc
@@ -1,23 +1,25 @@
 :_mod-docs-content-type: ASSEMBLY
 :context: configuring-templates
 [id="{context}"]
-= Configuring templates
+= About Software Templates
 
-Configure templates to create software components, and publish these components to different locations, such as the {product} software catalog, or Git repositories.
+Software Templates in {product} provide a streamlined way to create software components and publish them to different version control repositories like Git. Platform engineers create and maintain Software Templates in {product}.
 
-A template is a form composed of different UI fields that is defined in a YAML file. Templates include _actions_, which are steps that are executed in sequential order and can be executed conditionally.
+You can configure Software Templates to create software components, and publish these components to Git repositories. Once the components are published to Git repositories, register these components in the Software Catalog.
+
+A template is a form composed of different UI fields that is defined in a YAML file. Software Templates include _actions_, which are steps that are executed in sequential order and can be executed conditionally.
+
+* See link:https://developers.redhat.com/articles/2025/03/17/10-tips-better-backstage-software-templates#[10 tips for better Backstage Software Templates].
 
 include::modules/customizing-templates/proc-creating-templates.adoc[leveloffset=+1]
 include::modules/customizing-templates/ref-creating-templates.adoc[leveloffset=+1]
+include::modules/customizing-templates/proc-creating-a-new-software-component-using-templates.adoc[leveloffset=+1]
+include::modules/customizing-templates/proc-searching-and-filtering-software-templates.adoc[leveloffset=+1]
+include::modules/customizing-templates/proc-adding-templates.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
+* link:{authentication-book-url}#assembly-auth-provider-github[Enabling the GitHub authentication provider]
 * link:https://backstage.io/docs/features/software-templates/writing-templates[Backstage documentation - Writing Templates]
 * link:https://backstage.io/docs/features/software-templates/builtin-actions[Backstage documentation - Builtin actions]
 * link:https://backstage.io/docs/features/software-templates/writing-custom-actions[Backstage documentation - Writing Custom Actions]
-
-include::modules/customizing-templates/proc-adding-templates.adoc[leveloffset=+1]
-
-[role="_additional-resources"]
-.Additional resources
-* link:{authentication-book-url}#assembly-auth-provider-github[Enabling the GitHub authentication provider]
diff --git a/images/rhdh/template-creation-not-successful.png b/images/rhdh/template-creation-not-successful.png
diff --git a/images/rhdh/template-creation-successful.png b/images/rhdh/template-creation-successful.png
diff --git a/images/rhdh/template-editor.png b/images/rhdh/template-editor.png
diff --git a/modules/customizing-templates/proc-adding-templates.adoc b/modules/customizing-templates/proc-adding-templates.adoc
@@ -4,9 +4,9 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="proc-adding-templates_{context}"]
-= Importing an existing template to {product}
+= Importing an existing Software Template to {product}
 
-You can add an existing template to your {product} instance by using the Catalog Processor.
+You can add an existing Software Template to your {product} instance by using the Catalog Processor.
 
 .Prerequisites
 
@@ -15,7 +15,7 @@ You can add an existing template to your {product} instance by using the Catalog
 
 .Procedure
 
-* In the `{my-app-config-file}` configuration file, modify the `catalog.rules` section to include a rule for templates, and configure the `catalog.locations` section to point to the template that you want to add, as shown in the following example:
+* In the `{my-app-config-file}` configuration file, modify the `catalog.rules` section to include a rule for Software Templates, and configure the `catalog.locations` section to point to the Software Template that you want to add, as shown in the following example:
 +
 [source,yaml]
 ----
@@ -28,7 +28,7 @@ catalog:
       target: https://<repository_url>/example-template.yaml # <3>
 # ...
 ----
-<1> To allow new templates to be added to the catalog, you must add a `Template` rule.
+<1> To allow new Software Templates to be added to the catalog, you must add a `Template` rule.
 <2> If you are importing templates from a repository, such as GitHub or GitLab, use the `url` type.
 <3> Specify the URL for the template.
 
diff --git a/modules/customizing-templates/proc-creating-a-new-software-component-using-templates.adoc b/modules/customizing-templates/proc-creating-a-new-software-component-using-templates.adoc
@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-configuring-templates.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-creating-a-new-software-component-using-templates_{context}"]
+= Creating a new software component using Software Templates
+
+You can create a new software component using the standard Software Templates that the platform engineers have created. The scaffolding process runs in your {product} instance.
+
+.Procedure
+
+. In your {product} navigation menu, click *Catalog* > *Self-service*.
+. On the *Self-service* page, click *Choose* on the *Templates* tile to initiate the scaffolding process for a template.
+. Follow the wizard instructions as you enter the required details. You can choose parameters from a set of pre-defined options.
+* Optional: In the *Deployment Information* step, you have an option to *Create Workbench for OpenShift AI*. 
++
+[NOTE]
+====
+This step is available only for a few templates.
+====
+. In the *Review* step, verify the parameters you have entered and click *Create*.
++
+[NOTE]
+====
+* You can click *Cancel* to abort the software component creation during the template running step only if the current step supports the abort. The abort signal is then sent to a task and none of the following steps are executed. 
+* During the creation of the software component, click *Show Logs* to view the log information.
+====
+
+.Verification
+
+* If your software component is not created successfully, you can review the logs on the error page. To return to the *Self-service* page with the same template form and your previously entered values, click *Start Over*.
+
+image::rhdh/template-creation-not-successful.png[]
+
+* If your Software Template is created successfully, a success page similar to the example in the following image is displayed:
++
+--
+image::rhdh/template-creation-successful.png[template-creation-successful]
+--
diff --git a/modules/customizing-templates/proc-creating-templates.adoc b/modules/customizing-templates/proc-creating-templates.adoc
@@ -4,9 +4,9 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="proc-creating-templates_{context}"]
-= Creating a template by using the Template Editor
+= Creating a Software Template by using the Template Editor
 
-You can create a template by using the Template Editor.
+You can create a Software Template by using the Template Editor.
 
 .Procedure
 
@@ -16,7 +16,7 @@ image::rhdh/template-editor.png[Template Editor]
 ** Open the URL `\https://<rhdh_url>/create/edit` for your {product} instance.
 ** Click *Self-service* in the navigation menu of the {product} console, then click the overflow menu button and select *Template editor*.
 . Click *Edit Template Form*.
-. Optional: Modify the YAML definition for the parameters of your template. For more information about these parameters, see <<Creating a template as a YAML file>>.
+. Optional: Modify the YAML definition for the parameters of your template. For more information about these parameters, see <<Creating a Software Template as a YAML file>>.
 . In the *Name* field, enter a unique name for your template.
 . From the *Owner* drop-down menu, choose an owner for the template.
 . Click *Next*.
diff --git a/modules/customizing-templates/proc-searching-and-filtering-software-templates.adoc b/modules/customizing-templates/proc-searching-and-filtering-software-templates.adoc
@@ -0,0 +1,17 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-configuring-templates.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-searching-and-filtering-software-templates_{context}"]
+= Searching and filtering Software Templates in your {product} instance
+
+You can search and filter for the Software Template that you want to use to create a new software component.
+
+.Procedure
+
+To search and filter for a Software Template, complete the following steps:
+
+. In the {product} navigation menu, click *Catalog* > *Self-service*.
+. Type the name of the template you are looking for in the *Search* box.
+* If you are looking for templates in a certain category, you can use the *Categories* dropdown.
diff --git a/modules/customizing-templates/ref-creating-templates.adoc b/modules/customizing-templates/ref-creating-templates.adoc
@@ -4,11 +4,11 @@
 
 :_mod-docs-content-type: REFERENCE
 [id="ref-creating-templates_{context}"]
-= Creating a template as a YAML file
+= Creating a Software Template as a YAML file
 
-You can create a template by defining a `Template` object as a YAML file.
+You can create a Software Template by defining a `Template` object as a YAML file.
 
-The `Template` object describes the template and its metadata. It also contains required input variables and a list of actions that are executed by the scaffolding service.
+The `Template` object describes the Software Template and its metadata. It also contains required input variables and a list of actions that are executed by the scaffolding service.
 
 .`Template` object example
 [source,yaml]
@@ -56,10 +56,10 @@ spec:
         entityRef: ${{ steps['register'].output.entityRef }}
 # ...
 ----
-<1> Specify a name for the template.
-<2> Specify a title for the template. This is the title that is visible on the template tile in the *Self-service* view.
-<3> Specify a description for the template. This is the description that is visible on the template tile in the *Self-service* view.
-<4> Specify the ownership of the template. The `owner` field provides information about who is responsible for maintaining or overseeing the template within the system or organization. In the provided example, the `owner` field is set to `backstage/techdocs-core`. This means that this template belongs to the `techdocs-core` project in the `backstage` namespace.
+<1> Specify a name for the Software Template.
+<2> Specify a title for the Software Template. This is the title that is visible on the Software Template tile in the *Self-service* view.
+<3> Specify a description for the Software Template. This is the description that is visible on the Software Template tile in the *Self-service* view.
+<4> Specify the ownership of the Software Template. The `owner` field provides information about who is responsible for maintaining or overseeing the Software Template within the system or organization. In the provided example, the `owner` field is set to `backstage/techdocs-core`. This means that this Software Template belongs to the `techdocs-core` project in the `backstage` namespace.
 <5> Specify the component type. Any string value is accepted for this required field, but your organization should establish a proper taxonomy for these. {product} instances may read this field and behave differently depending on its value. For example, a `website` type component may present tooling in the {product} interface that is specific to just websites.
 +
 The following values are common for this field:
@@ -69,7 +69,7 @@ The following values are common for this field:
 `website`:: A website.
 `library`:: A software library, such as an npm module or a Java library.
 --
-<6> Use the `parameters` section to specify parameters for user input that are shown in a form view when a user creates a component by using the template in the {product} console. Each `parameters` subsection, defined by a title and properties, creates a new form page with that definition.
+<6> Use the `parameters` section to specify parameters for user input that are shown in a form view when a user creates a component by using the Software Template in the {product} console. Each `parameters` subsection, defined by a title and properties, creates a new form page with that definition.
 <7> Use the `steps` section to specify steps that are executed in the backend. These steps must be defined by using a unique step ID, a name, and an action. You can view actions that are available on your {product} instance by visiting the URL `\https://<rhdh_url>/create/actions`.
 <8> Use the `output` section to specify the structure of output data that is created when the template is used. The `output` section, particularly the `links` subsection, provides valuable references and URLs that users can utilize to access and interact with components that are created from the template.
 <9> Provides a reference or URL to the repository associated with the generated component.
