Modularlization (#1596)

Author: pabel-rh

modules/customizing-templates/ref-creating-templates.adoc

@@ -7,19 +7,18 @@ You can create a Software Template by defining a `Template` object as a YAML fil
 
 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]
 ----
 apiVersion: scaffolder.backstage.io/v1beta3
 kind: Template
 metadata:
-  name: template-name # <1>
-  title: Example template # <2>
-  description: An example template for v1beta3 scaffolder. # <3>
+  name: template-name
+  title: Example template
+  description: An example template for v1beta3 scaffolder.
 spec:
-  owner: backstage/techdocs-core # <4>
-  type: service # <5>
-  parameters: # <6>
+  owner: backstage/techdocs-core
+  type: service
+  parameters:
     - title: Fill in some steps
       required:
         - name
@@ -53,11 +52,14 @@ spec:
         entityRef: ${{ steps['register'].output.entityRef }}
 # ...
 ----
-<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.
++
+where:
+
+`metadata.name`:: Enter a name for the Software Template.
+`metadata.title`:: Enter a title for the Software Template. This is the title that is visible on the Software Template tile in the *Self-service* view.
+`metadata.description`:: Enter a description for the Software Template. This is the description that is visible on the Software Template tile in the *Self-service* view.
+`spec.owner`:: Enter 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.
+`spec.type`:: Enter 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:
 +
@@ -66,8 +68,8 @@ 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 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.
-<10> Provides a reference or URL that allows users to open the generated component in a catalog or directory where various components are listed.
+`spec.parameters`:: 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.
+`spec.steps`:: 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`.
+`spec.output`:: 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.
+`spec.output.links.title`:: Provides a reference or URL to the repository associated with the generated component.
+`spec.output.links.title`:: Provides a reference or URL that allows users to open the generated component in a catalog or directory where various components are listed.

modules/importing-and-using-an-existing-template-for-faster-development/proc-adding-templates.adoc

@@ -19,15 +19,18 @@ You can add an existing Software Template to your {product} instance by using th
 # ...
 catalog:
   rules:
-    - allow: [Template] # <1>
+    - allow: [Template]
   locations:
-    - type: url # <2>
-      target: https://<repository_url>/example-template.yaml # <3>
+    - type: url
+      target: https://<repository_url>/example-template.yaml
 # ...
 ----
-<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.
++
+where: 
+
+`catalog.rules.allow`:: Specify the `Template` rule to allow new Software Templates in the catalog.
+`catalog.locations.type`:: Specify the `url` type when importing templates from a repository (for example, GitHub or GitLab).
+`catalog.locations.target`:: Specify the URL for the template.
 
 .Verification
 

modules/importing-and-using-an-existing-template-for-faster-development/proc-creating-templates.adoc

@@ -15,8 +15,6 @@ Alternately, you can use the Template Editor to do any of the following actions:
 
 .Procedure
 
-To create a Software Template by using the Template Editor templates, complete the following steps:
-
 . In your {product} navigation menu, click *Catalog > Self-service*. Alternatively, to go to *Self-service* page, in your header menu, click the (+) icon.
 . Click the *More options* icon and select *Manage Templates*.
 +

modules/importing-and-using-an-existing-template-for-faster-development/proc-searching-and-filtering-software-templates.adoc

@@ -7,8 +7,6 @@ You can search and filter for the Software Template that you want to use to crea
 
 .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.

modules/streamline-software-development-and-management/proc-enabling-and-authorizing-bulk-import-capabilities.adoc

@@ -9,12 +9,10 @@ This feature is available for GitHub repositories and GitLab projects.
 .Prerequisites
 * For GitHub only: You have {integrating-with-github-book-link}#enabling-github-repository-discovery[enabled GitHub repository discovery].
 
-
 .Procedure
 . The Bulk Import plugins are installed but disabled by default.
 To enable the `./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic` and `./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import` plugins, edit your `dynamic-plugins.yaml` with the following content:
 +
-.`dynamic-plugins.yaml` fragment
 [source,yaml]
 ----
 plugins:
@@ -26,7 +24,7 @@ plugins:
 +
 See {installing-and-viewing-plugins-book-link}[{installing-and-viewing-plugins-book-title}].
 
-. Configure the required `bulk.import` RBAC permission for the users who are not administrators as follows:
+. Configure the required `bulk.import` RBAC permission for the users who are not administrators as shown in the following code:
 +
 .`rbac-policy.csv` fragment
 [source,csv,subs="+quotes"]

modules/streamline-software-development-and-management/proc-managing-repositories-after-import-to-stay-organized.adoc

@@ -10,7 +10,7 @@ You can oversee and manage the Git repositories that are imported to the {produc
 
 
 .Procedure
-. Click *Bulk Import* in the left sidebar to display all the current GitHub repositories and GitLab projects that are being tracked as Import jobs, along with their status.
+* Click *Bulk Import* in the left sidebar to display all the current GitHub repositories and GitLab projects that are being tracked as Import jobs, along with their status.
 
 Added:: The Git repository is added to the {product-short} catalog after the import pull request is merged or if the Git repository already contained a `catalog-info.yaml` file during the bulk import.
 Note that it may take a few minutes for the entities to be available in the catalog.