Review abstracts in Adding content

.cursor/skills/abstract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: abstract
-description: Review or write abstract
+description: Review or write an abstract (DITA short description) for a documentation module
 ---
 # Review or write abstract
 
@@ -16,41 +16,18 @@ It is prefixed by the `[role="_abstract"]` AsciiDoc tag.
 
 Abstracts, also called short descriptions, help readers and AI-powered search tools find the information that they need and confirm that they are in the right place.
 
-Abstracts typically contain the following information:
-
-- The "What"
-- The "Why"
-- Where appropriate, an example use case
-
 ## Instructions
 
 When reviewing or writing the abstract, follow these principles:
 
-- Ensure the abstract explains the What and the Why as defined in the section "Definition of an abstract".
-  - For the `What` part, state the action or feature clearly. For example, what the user must do or can do (in procedure modules), what the user needs to understand (in concept modules), or what is being listed (in reference modules).
-  - For the `Why` part, state the business value, benefit, or goal. For example, why the user should complete the action (in procedure modules), why the concept is important to users (in concept modules), or why the user would look up the information (in reference modules).
-  - For the `Example use case part`, consider including in what situations a user might find the contents of the module useful.
-  - Do not simply repeat the heading of the module; build upon it.
-- Follow these user-centric language guidelines:
-  - Avoid documentation self-referential language (for example: avoid "This procedure..." or "This module").
-  - Avoid feature-centric language (for example: avoid "This feature...").
-  - Use user-centric language (for example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]").
+- Do not simply repeat the heading of the module; build upon it.
+- Avoid self-referential language (for example: avoid "This procedure...", "This module...", "This table...").
+- Avoid feature-centric language (for example: avoid "This feature...").
+- Do not use sentence fragments.
+- When needed, address the user as "you".
 - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph.
-
-## Examples of good abstracts
-
-| Heading | Example abstract (procedure) |
-| :--- | :--- |
-| Browsing hosts in {ProjectWebUI} | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. |
-| Cloning hosts in {Project} | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. |
-| Editing system purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. |
-
-| Heading | Example abstract (concept) |
-| :--- | :--- |
-| Security considerations in {Project} | {Project} supports multiple security mechanisms to provide additional layers of protection. Implementing these security features enhances the overall security of your {Project} deployment. |
-| Overview of authentication methods in {Project} | The authentication methods you can configure depend on the authentication source you are using. If the native authentication features provided by {Project} are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements. |
-
-| Heading | Example abstract (reference) |
-| :--- | :--- |
-| Subscriptions usage data | For the purposes of expense management and to optimize your spending, track your subscriptions usage data that you can get from your {Project} environment and Red Hat. You can track usage, capacity, and utilization of your Red Hat subscriptions. |
-| Host global status overview | You can use the host global status in {Project} to see at a glance whether a host is OK, needs attention (Warning), or has errors. The status appears on the Hosts Overview page and helps you prioritize which hosts to investigate. |
+- Write one sentence per line.
+- For module-type-specific abstract rules, look up the reference file that matches the `:_mod-docs-content-type:` AsciiDoc attribute in the module (open and apply that file in full):
+  - `CONCEPT` → [references/concept.md](references/concept.md)
+  - `PROCEDURE` → [references/procedure.md](references/procedure.md)
+  - `REFERENCE` → [references/reference.md](references/reference.md)

.cursor/skills/abstract/references/concept.md

@@ -0,0 +1,15 @@
+# Abstract instructions: concept modules
+
+When the module has `:_mod-docs-content-type: CONCEPT`, follow these rules for the abstract (short description):
+
+- Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "Why do I care about this?"
+- If the concept is unfamiliar, start with a brief definition.
+- Avoid using the short description to lead in or build up to a topic.
+- Include the main point of the concept topic.
+
+## Examples of good abstracts
+
+| Heading | Example abstract (concept) |
+| :--- | :--- |
+| Security considerations in {Project} | {Project} supports multiple security mechanisms to provide additional layers of protection. Implementing these security features enhances the overall security of your {Project} deployment. |
+| Overview of authentication methods in {Project} | The authentication methods you can configure depend on the authentication source you are using. If the native authentication features provided by {Project} are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements. |

.cursor/skills/abstract/references/procedure.md

@@ -0,0 +1,17 @@
+# Abstract instructions: procedure modules
+
+When the module has `:_mod-docs-content-type: PROCEDURE`, follow these rules for the abstract (short description):
+
+- Use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", or "[Action] [what] to [why]".
+- Explain the task that users can accomplish, the benefits of the task, and the purpose of the task.
+- Do not simply repeat the title.
+- Include information that will help users understand when the task is appropriate or necessary.
+- When the abstract is too short, thin, or generic, add more information about why the task is beneficial.
+
+## Examples of good abstracts
+
+| Heading | Example abstract (procedure) |
+| :--- | :--- |
+| Browsing hosts in {ProjectWebUI} | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. |
+| Cloning hosts in {Project} | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. |
+| Editing system purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. |

.cursor/skills/abstract/references/reference.md

@@ -0,0 +1,12 @@
+# Abstract instructions: reference modules
+
+When the module has `:_mod-docs-content-type: REFERENCE`, follow these rules for the abstract (short description):
+
+- Briefly describe what the reference item does, what it is, or what it is used for.
+
+## Examples of good abstracts
+
+| Heading | Example abstract (reference) |
+| :--- | :--- |
+| Subscriptions usage data | For the purposes of expense management and to optimize your spending, track your subscriptions usage data that you can get from your {Project} environment and Red Hat. You can track usage, capacity, and utilization of your Red Hat subscriptions. |
+| Host global status overview | You can use the host global status in {Project} to see at a glance whether a host is OK, needs attention (Warning), or has errors. The status appears on the Hosts Overview page and helps you prioritize which hosts to investigate. |

guides/common/modules/con_adding-content-to-foreman.adoc

@@ -4,4 +4,5 @@
 = Adding content to {Project}
 
 [role="_abstract"]
-This chapter outlines how you can import different types of {customcontent} to {Project}.
+You organize content in products and repositories and secure upstream access with content credentials before you create custom products and repositories.
+You synchronize from upstream URLs, upload your own content, and use repository definitions when you plan client repositories.

guides/common/modules/con_authenticating-and-securing-content-with-content-credentials.adoc

@@ -4,19 +4,18 @@
 = Authenticating and securing content with content credentials
 
 [role="_abstract"]
-Upstream content often uses HTTPS and signed metadata or packages.
-Import SSL certificates when upstream servers use custom or private certificate authorities so {Project} can connect securely.
+Upstream repositories use HTTPS and signed metadata or packages; import SSL certificates when upstreams use custom or private CAs so {Project} connects securely.
 ifdef::katello[]
-Import GPG keys so {Project} and registered hosts can verify signatures on RPM packages or metadata of Deb content.
+Import GPG keys so {Project} and hosts can validate RPM packages and Debian repository metadata.
 endif::[]
 ifdef::orcharhino[]
 ifdef::almalinux,amazon_linux,centos,oracle_linux,red_hat_enterprise_linux,rocky_linux,suse_linux_enterprise_server[]
-Import GPG keys so registered hosts can verify signatures on Yum content when they consume content from {Project}.
+Import GPG keys so registered hosts can verify Yum signatures when they consume content from {Project}.
 endif::[]
 ifdef::debian,ubuntu[]
-Import GPG keys so {Project} can verify signatures on metadata of Deb content.
+Import GPG keys so {Project} can verify signatures on Deb repository metadata.
 endif::[]
 endif::[]
 ifdef::satellite[]
-Import GPG keys so registered hosts can verify signatures on Yum content when they consume content from {Project}.
+Import GPG keys so registered hosts can verify Yum signatures when they consume content from {Project}.
 endif::[]

guides/common/modules/con_creating-products.adoc

@@ -5,7 +5,7 @@
 
 [role="_abstract"]
 A product in {Project} groups related repositories.
-Create a {customproduct} before you add {customrepos}.
+You create a {customproduct} before you add {customrepos}.
 
 ifndef::satellite[]
 [NOTE]

guides/common/modules/con_products-and-repositories.adoc

@@ -4,9 +4,8 @@
 = Products and repositories in {Project}
 
 [role="_abstract"]
-Content in {Project} is organized into products and repositories.
-A repository is a collection of content, such as packages, container images, or files.
-A collection of repositories forms a product.
+{Project} organizes content into products, each grouping repositories that store packages, container images, or files.
+The relationship between products and repositories is the same for all content types, and each custom product supplies a subscription for host access.
 
 ifdef::satellite[]
 Both Red Hat content and custom content in {Project} have similarities:

guides/common/modules/con_uploading-content-to-repositories.adoc

@@ -4,4 +4,4 @@
 = Uploading content to {customrepos}
 
 [role="_abstract"]
-You can upload content to {customrepos} to distribute content that you cannot synchronize from an upstream URL.
+Upload content to {customrepos} when you must distribute software that is not available from any upstream synchronization URL.

guides/common/modules/proc_adding-custom-rpm-repositories-by-using-cli.adoc

@@ -4,11 +4,8 @@
 = Adding {customrpm} repositories by using Hammer CLI
 
 [role="_abstract"]
-You can add {customrpm} repositories to {Project} by using Hammer CLI.
-
-The *Products* window in the {ProjectWebUI} also provides a *Repo Discovery* function that finds all repositories from a URL and you can select which ones to add to your {customproduct}.
-For example, you can use the *Repo Discovery* to search `https://download.postgresql.org/pub/repos/yum/16/redhat/` and list all repositories for different {EL} versions and architectures.
-This helps users save time importing multiple repositories from a single source.
+You add {customrpm} repositories to a product so hosts can synchronize or upload third-party or internal packages through {Project}.
+Use Hammer CLI when you automate repository creation or repeat the same settings across environments.
 
 ifdef::satellite[]
 [NOTE]

guides/common/modules/proc_adding-custom-rpm-repositories-by-using-web-ui.adoc

@@ -4,11 +4,8 @@
 = Adding {customrpm} repositories by using {ProjectWebUI}
 
 [role="_abstract"]
-You can add {customrpm} repositories to {Project} by using the {ProjectWebUI}.
-
-The *Products* window in the {ProjectWebUI} also provides a *Repo Discovery* function that finds all repositories from a URL and you can select which ones to add to your {customproduct}.
-For example, you can use the *Repo Discovery* to search `https://download.postgresql.org/pub/repos/yum/16/redhat/` and list all repositories for different {EL} versions and architectures.
-This helps users save time importing multiple repositories from a single source.
+You add {customrpm} repositories to a product so hosts can synchronize or upload third-party or internal packages through {Project}.
+Use {ProjectWebUI} when you create repositories manually or run *Repo Discovery* against a vendor URL to import many related repositories at once.
 
 ifdef::satellite[]
 [NOTE]

guides/common/modules/proc_adding-deb-repositories-by-using-cli.adoc

@@ -4,7 +4,8 @@
 = Adding Deb repositories by using Hammer CLI
 
 [role="_abstract"]
-You can add Deb repositories to {Project} by using Hammer CLI.
+You add Deb repositories in {Project} to mirror Debian or Ubuntu suites for managed hosts.
+Use Hammer CLI when you define releases, components, and architectures from the command line.
 
 .Prerequisites
 * You have extracted and imported the GPG key that you want to use to verify signatures of the `Release` files.

guides/common/modules/proc_adding-deb-repositories-by-using-web-ui.adoc

@@ -4,7 +4,8 @@
 = Adding Deb repositories by using {ProjectWebUI}
 
 [role="_abstract"]
-You can add Deb repositories to {Project} by using the {ProjectWebUI}.
+You add Deb repositories in {Project} to mirror Debian or Ubuntu suites for managed hosts.
+Use {ProjectWebUI} when you configure distribution paths, components, and upstream URLs interactively.
 
 .Prerequisites
 * You have extracted and imported the GPG key that you want to use to verify signatures of the `Release` files.

guides/common/modules/proc_creating-a-custom-product-by-using-cli.adoc

@@ -4,7 +4,8 @@
 = Creating a {customproduct} by using Hammer CLI
 
 [role="_abstract"]
-Create a {customproduct} so that you can add repositories to the {customproduct}.
+You create a {customproduct} in {Project} to group repositories and optional SSL or GPG credentials under one manageable label.
+Use Hammer CLI when you automate product creation alongside repositories and credentials.
 
 .Procedure
 * Create a product:

guides/common/modules/proc_creating-a-custom-product-by-using-web-ui.adoc

@@ -4,7 +4,8 @@
 = Creating a {customproduct} by using {ProjectWebUI}
 
 [role="_abstract"]
-Create a {customproduct} so that you can add repositories to the {customproduct}.
+You create a {customproduct} in {Project} to group repositories and optional SSL or GPG credentials under one manageable label.
+Use a dedicated product when you want lifecycle, permissions, and sync plans scoped separately from other software you publish.
 
 .Procedure
 . In the {ProjectWebUI}, navigate to *Content* > *Products*, click *Create Product*.

guides/common/modules/proc_enabling-red-hat-repositories-by-using-cli.adoc

@@ -4,6 +4,9 @@
 = Enabling Red{nbsp}Hat repositories by using Hammer CLI
 
 [role="_abstract"]
+You enable Red{nbsp}Hat repository sets in {Project} so subscribed product content can synchronize into Library before hosts consume it.
+Use Hammer CLI when you script enablement or integrate it with other server automation.
+
 If outside network access requires usage of an HTTP proxy, configure a default HTTP proxy for your {ProjectServer}.
 For more information, see {InstallingServerDocURL}adding-a-default-http-proxy-by-using-cli[Adding a default HTTP proxy to {Project}].
 

guides/common/modules/proc_enabling-red-hat-repositories-by-using-web-ui.adoc

@@ -4,6 +4,9 @@
 = Enabling Red{nbsp}Hat repositories by using {ProjectWebUI}
 
 [role="_abstract"]
+You enable Red{nbsp}Hat repository sets in {Project} so subscribed product content can synchronize into Library before hosts consume it.
+Use {ProjectWebUI} when you want to browse recommended sets and enable release versions and base architectures interactively.
+
 If outside network access requires usage of an HTTP proxy, configure a default HTTP proxy for your {ProjectServer}.
 For more information, see {InstallingServerDocURL}adding-a-default-http-proxy-by-using-web-ui[Adding a default HTTP proxy to {Project}].
 

guides/common/modules/proc_extracting-gpg-public-key-fingerprints-from-release-files.adoc

@@ -4,8 +4,7 @@
 = Extracting GPG public key fingerprints from Release files
 
 [role="_abstract"]
-You can use GPG public keys to verify the authenticity of Deb repositories by verifying the signature of the `Release` file.
-This example verifies the signature for the `Release` file from Debian 11.
+You extract GPG public key fingerprints from signed `Release` files so you can import the matching keys that secure Deb repositories in {Project}.
 
 .Procedure
 . Download the `Release` and `Release.gpg` files:

guides/common/modules/proc_importing-a-custom-gpg-key-by-using-cli.adoc

@@ -4,8 +4,8 @@
 = Importing a {customgpg} key by using Hammer CLI
 
 [role="_abstract"]
-When hosts consume signed {customcontent}, ensure that the hosts are configured to validate the installation of packages with the appropriate GPG Key.
-This helps to ensure that only packages from authorized sources can be installed.
+You import a {customgpg} key into {Project} when you synchronize signed {customcontent} so repository metadata and hosts can validate packages against the public key your vendor publishes.
+Approved keys help ensure hosts install only packages that carry signatures from sources you trust.
 
 ifdef::satellite[]
 Red{nbsp}Hat content is already configured with the appropriate GPG key and thus GPG Key management of Red{nbsp}Hat repositories is not supported.

guides/common/modules/proc_importing-a-custom-gpg-key-by-using-web-ui.adoc

@@ -4,8 +4,8 @@
 = Importing a {customgpg} key by using {ProjectWebUI}
 
 [role="_abstract"]
-When hosts consume signed {customcontent}, ensure that the hosts are configured to validate the installation of packages with the appropriate GPG Key.
-This helps to ensure that only packages from authorized sources can be installed.
+You import a {customgpg} key into {Project} when you synchronize signed {customcontent} so repository metadata and hosts can validate packages against the public key your vendor publishes.
+Approved keys help ensure hosts install only packages that carry signatures from sources you trust.
 
 ifdef::satellite[]
 Red{nbsp}Hat content is already configured with the appropriate GPG key and thus GPG Key management of Red{nbsp}Hat repositories is not supported.

guides/common/modules/proc_importing-custom-ssl-certificates-by-using-cli.adoc

@@ -4,10 +4,7 @@
 = Importing {customssl} certificates by using Hammer CLI
 
 [role="_abstract"]
-Before you synchronize {customcontent} from an external source, you might need to import SSL certificates into your {Project}.
-This might include client certs and keys or CA certificates for the upstream repositories you want to synchronize.
-
-If you require SSL certificates and keys to download packages, you can add them to {Project}.
+You import SSL certificates or keys into {Project} so upstream synchronization over HTTPS can trust custom certificate authorities or present client credentials when vendors require mutual TLS.
 
 .Procedure
 . Copy the SSL certificate to your {ProjectServer}:

guides/common/modules/proc_importing-custom-ssl-certificates-by-using-web-ui.adoc

@@ -4,10 +4,7 @@
 = Importing {customssl} certificates by using {ProjectWebUI}
 
 [role="_abstract"]
-Before you synchronize {customcontent} from an external source, you might need to import SSL certificates into your {Project}.
-This might include client certs and keys or CA certificates for the upstream repositories you want to synchronize.
-
-If you require SSL certificates and keys to download packages, you can add them to {Project}.
+You import SSL certificates or keys into {Project} so upstream synchronization over HTTPS can trust custom certificate authorities or present client credentials when vendors require mutual TLS.
 
 .Procedure
 . In the {ProjectWebUI}, navigate to *Content* > *Content Credentials*.

guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-cli.adoc

@@ -4,7 +4,7 @@
 = Uploading content to {customrpm} repositories by using Hammer CLI
 
 [role="_abstract"]
-You can upload individual RPMs and source RPMs to {customrpm} repositories by using Hammer CLI.
+You upload RPM or source RPM packages with Hammer CLI when you need scripted bulk uploads or source RPM support beyond the web UI.
 
 .Procedure
 * Upload an RPM package: