From 779de82b158f834cb1820c84f2707fb45304fdd9 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Tue, 5 May 2026 22:10:55 +0200 Subject: [PATCH 01/14] Enhance abstract skill for DITA short descriptions --- .claude/skills/abstract/SKILL.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 11aa813866f..6cc2201ed0f 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -27,15 +27,32 @@ Abstracts typically contain the following information: 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 `What` part, state the action or definition clearly. + - For the `Why` part, state the business value, benefit, or goal. - 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 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]"). - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. +- Do not remove useful information. If needed, just move it to the next paragraph instead of replacing it. + +### Instructions for concept modules + +- 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, you can start with a brief definition. +- Avoid using the short description to lead in or build up to a topic. +- The short description paragraph should contain the main point of the concept topic. + +### Instructions for procedure modules + +- The short description should explain the task that users can accomplish, the benefits of the task, and the purpose of the task. Do not simply repeat the title. Try to include information that will help users understand when the task is appropriate or why the task is necessary. Avoid stating the obvious, such as "You can use XYZ to do A" as the only statement in the short description for the task. In some cases, add more information about why the task is beneficial. + +### Instructions for reference modules + +- Briefly describe what the reference item does, what it is, or what it is used for. + ## Examples of good abstracts From 5d24fe690a145ab5c07b72235b43b32feeebedd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lena=20Ansorgov=C3=A1?= Date: Tue, 5 May 2026 22:18:22 +0200 Subject: [PATCH 02/14] Apply suggestion from @Lennonka --- .claude/skills/abstract/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 6cc2201ed0f..7add2b11dc7 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -27,7 +27,7 @@ Abstracts typically contain the following information: 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 definition clearly. + - For the `What` part, state the action or concept clearly. - For the `Why` part, state the business value, benefit, or goal. - 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. From 99410096ddc243878811baff0798de1c74877712 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Tue, 5 May 2026 22:43:55 +0200 Subject: [PATCH 03/14] Enforce instructions for module types --- .claude/skills/abstract/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 7add2b11dc7..92a105f4e98 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -37,6 +37,7 @@ When reviewing or writing the abstract, follow these principles: - Use user-centric language (for example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]"). - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. - Do not remove useful information. If needed, just move it to the next paragraph instead of replacing it. +- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` tag in the file. ### Instructions for concept modules @@ -53,7 +54,6 @@ When reviewing or writing the abstract, follow these principles: - Briefly describe what the reference item does, what it is, or what it is used for. - ## Examples of good abstracts | Heading | Example abstract (procedure) | From 98a5f4dc1c290e2ce463406cde52a3461663177e Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Tue, 5 May 2026 23:11:27 +0200 Subject: [PATCH 04/14] Clean up generic instructions --- .claude/skills/abstract/SKILL.md | 35 +++++++++++++------------------- 1 file changed, 14 insertions(+), 21 deletions(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 92a105f4e98..4ed89cdb49c 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/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,39 +16,32 @@ 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 concept clearly. - - For the `Why` part, state the business value, benefit, or goal. - - 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 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..." or "This module..."). +- Avoid feature-centric language (for example: avoid "This feature..."). - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. -- Do not remove useful information. If needed, just move it to the next paragraph instead of replacing it. -- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` tag in the file. +- Do not use sentence fragments. Always use full sentences. +- Write one sentence per line. +- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` AsciiDoc attribute in the file. Use the subsection whose name matches the attribute value (CONCEPT → concept, PROCEDURE → procedure, REFERENCE → reference). ### Instructions for concept modules - 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, you can start with a brief definition. +- If the concept is unfamiliar, start with a brief definition. - Avoid using the short description to lead in or build up to a topic. -- The short description paragraph should contain the main point of the concept topic. +- Include the main point of the concept topic. ### Instructions for procedure modules -- The short description should explain the task that users can accomplish, the benefits of the task, and the purpose of the task. Do not simply repeat the title. Try to include information that will help users understand when the task is appropriate or why the task is necessary. Avoid stating the obvious, such as "You can use XYZ to do A" as the only statement in the short description for the task. In some cases, add more information about why the task is beneficial. +- 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. +- Use user-centric language. For example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]". ### Instructions for reference modules From 556cd90ea2f668d44f77c525d60d98aef285df66 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Tue, 5 May 2026 23:41:07 +0200 Subject: [PATCH 05/14] Reorder stuff --- .claude/skills/abstract/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 4ed89cdb49c..66fecbd9372 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -26,24 +26,24 @@ When reviewing or writing the abstract, follow these principles: - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. - Do not use sentence fragments. Always use full sentences. - Write one sentence per line. -- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` AsciiDoc attribute in the file. Use the subsection whose name matches the attribute value (CONCEPT → concept, PROCEDURE → procedure, REFERENCE → reference). +- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` AsciiDoc attribute in the file. Use the subsection whose name matches the attribute value. -### Instructions for concept modules +### Instructions for CONCEPT modules - 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. -### Instructions for procedure modules +### Instructions for PROCEDURE modules +- Use user-centric language. For example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[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. -- Use user-centric language. For example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]". -### Instructions for reference modules +### Instructions for REFERENCE modules - Briefly describe what the reference item does, what it is, or what it is used for. From f962926d068ef3ed779a989b55c15f74b0c74c85 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Wed, 6 May 2026 00:24:21 +0200 Subject: [PATCH 06/14] Drop example keyword to enforce usage --- .claude/skills/abstract/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 66fecbd9372..26932eb8bf0 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -37,7 +37,7 @@ When reviewing or writing the abstract, follow these principles: ### Instructions for PROCEDURE modules -- Use user-centric language. For example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]". +- Use user-centric language. Use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[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. From 3d32b37f84f50aff3b7ff627f7407d03f6293ce1 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Wed, 6 May 2026 00:44:04 +0200 Subject: [PATCH 07/14] Improve content type following --- .claude/skills/abstract/SKILL.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 26932eb8bf0..18aa85f1959 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -23,27 +23,28 @@ When reviewing or writing the abstract, follow these principles: - Do not simply repeat the heading of the module; build upon it. - Avoid self-referential language (for example: avoid "This procedure..." or "This module..."). - Avoid feature-centric language (for example: avoid "This feature..."). +- Use user-centric language; address the user directly as "you". - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. - Do not use sentence fragments. Always use full sentences. - Write one sentence per line. -- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` AsciiDoc attribute in the file. Use the subsection whose name matches the attribute value. +- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` AsciiDoc attribute in the file. Use the subsection whose name matches the attribute value (CONCEPT -> concept, PROCEDURE -> procedure, REFERENCE -> reference). -### Instructions for CONCEPT modules +### Instructions for concept modules - 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. -### Instructions for PROCEDURE modules +### Instructions for procedure modules -- Use user-centric language. Use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]". +- 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. -### Instructions for REFERENCE modules +### Instructions for reference modules - Briefly describe what the reference item does, what it is, or what it is used for. From 7f8e893294f9e94e35d959410badf80c44dafce2 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Wed, 6 May 2026 01:19:16 +0200 Subject: [PATCH 08/14] Extract content-type specific instructions to references --- .claude/skills/abstract/SKILL.md | 24 ++++--------------- .cursor/skills/abstract/references/concept.md | 8 +++++++ .../skills/abstract/references/procedure.md | 9 +++++++ .../skills/abstract/references/reference.md | 5 ++++ 4 files changed, 26 insertions(+), 20 deletions(-) create mode 100644 .cursor/skills/abstract/references/concept.md create mode 100644 .cursor/skills/abstract/references/procedure.md create mode 100644 .cursor/skills/abstract/references/reference.md diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 18aa85f1959..2270dc39329 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -27,26 +27,10 @@ When reviewing or writing the abstract, follow these principles: - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. - Do not use sentence fragments. Always use full sentences. - Write one sentence per line. -- Follow instructions below for particular module types. The module type is defined by the `:_mod-docs-content-type:` AsciiDoc attribute in the file. Use the subsection whose name matches the attribute value (CONCEPT -> concept, PROCEDURE -> procedure, REFERENCE -> reference). - -### Instructions for concept modules - -- 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. - -### Instructions for procedure modules - -- 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. - -### Instructions for reference modules - -- Briefly describe what the reference item does, what it is, or what it is used for. +- 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) ## Examples of good abstracts diff --git a/.cursor/skills/abstract/references/concept.md b/.cursor/skills/abstract/references/concept.md new file mode 100644 index 00000000000..bf1587bc50c --- /dev/null +++ b/.cursor/skills/abstract/references/concept.md @@ -0,0 +1,8 @@ +# 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. diff --git a/.cursor/skills/abstract/references/procedure.md b/.cursor/skills/abstract/references/procedure.md new file mode 100644 index 00000000000..50f682869ba --- /dev/null +++ b/.cursor/skills/abstract/references/procedure.md @@ -0,0 +1,9 @@ +# 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. diff --git a/.cursor/skills/abstract/references/reference.md b/.cursor/skills/abstract/references/reference.md new file mode 100644 index 00000000000..bcf58fbf7da --- /dev/null +++ b/.cursor/skills/abstract/references/reference.md @@ -0,0 +1,5 @@ +# 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. From 85081dcec90e4d8a8459bb51b3af3a90b519e06c Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Wed, 6 May 2026 02:10:55 +0200 Subject: [PATCH 09/14] Move examples to references --- .claude/skills/abstract/SKILL.md | 18 ------------------ .cursor/skills/abstract/references/concept.md | 7 +++++++ .../skills/abstract/references/procedure.md | 8 ++++++++ .../skills/abstract/references/reference.md | 7 +++++++ 4 files changed, 22 insertions(+), 18 deletions(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 2270dc39329..2f1048fe2fb 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -31,21 +31,3 @@ When reviewing or writing the abstract, follow these principles: - `CONCEPT` → [references/concept.md](references/concept.md) - `PROCEDURE` → [references/procedure.md](references/procedure.md) - `REFERENCE` → [references/reference.md](references/reference.md) - -## 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. | diff --git a/.cursor/skills/abstract/references/concept.md b/.cursor/skills/abstract/references/concept.md index bf1587bc50c..bfc1b293b40 100644 --- a/.cursor/skills/abstract/references/concept.md +++ b/.cursor/skills/abstract/references/concept.md @@ -6,3 +6,10 @@ When the module has `:_mod-docs-content-type: CONCEPT`, follow these rules for t - 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. | diff --git a/.cursor/skills/abstract/references/procedure.md b/.cursor/skills/abstract/references/procedure.md index 50f682869ba..d1047ee0317 100644 --- a/.cursor/skills/abstract/references/procedure.md +++ b/.cursor/skills/abstract/references/procedure.md @@ -7,3 +7,11 @@ When the module has `:_mod-docs-content-type: PROCEDURE`, follow these rules for - 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. | diff --git a/.cursor/skills/abstract/references/reference.md b/.cursor/skills/abstract/references/reference.md index bcf58fbf7da..fdf547af8c3 100644 --- a/.cursor/skills/abstract/references/reference.md +++ b/.cursor/skills/abstract/references/reference.md @@ -3,3 +3,10 @@ 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. | From 3b77ef0f1480f87c421a5608db976af58484abb3 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Wed, 6 May 2026 02:13:59 +0200 Subject: [PATCH 10/14] Fine tune wording --- .claude/skills/abstract/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 2f1048fe2fb..cd87f55df38 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -21,11 +21,11 @@ Abstracts, also called short descriptions, help readers and AI-powered search to When reviewing or writing the abstract, follow these principles: - Do not simply repeat the heading of the module; build upon it. -- Avoid self-referential language (for example: avoid "This procedure..." or "This module..."). +- Avoid self-referential language (for example: avoid "This procedure...", "This module...", "This table..."). - Avoid feature-centric language (for example: avoid "This feature..."). -- Use user-centric language; address the user directly as "you". +- 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. -- Do not use sentence fragments. Always use full sentences. - 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) From 33fc77fafef36b0ed0adb1c41e3b963fc93862f1 Mon Sep 17 00:00:00 2001 From: Lena Ansorgova Date: Tue, 19 May 2026 14:05:27 +0200 Subject: [PATCH 11/14] Incorporate feedback --- .claude/skills/abstract/SKILL.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index cd87f55df38..2502bb7868e 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -16,6 +16,12 @@ 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: @@ -26,7 +32,6 @@ When reviewing or writing the abstract, follow these principles: - 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. -- 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) From b9055e6b9e84b2eef8df382cb01511607a67fd20 Mon Sep 17 00:00:00 2001 From: Lena Ansorge Date: Wed, 20 May 2026 15:40:52 +0200 Subject: [PATCH 12/14] Apply suggestions from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Aneta Petrová --- .claude/skills/abstract/SKILL.md | 4 ++-- .cursor/skills/abstract/references/concept.md | 4 +--- .cursor/skills/abstract/references/procedure.md | 1 - 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/.claude/skills/abstract/SKILL.md b/.claude/skills/abstract/SKILL.md index 2502bb7868e..20ce057e45a 100644 --- a/.claude/skills/abstract/SKILL.md +++ b/.claude/skills/abstract/SKILL.md @@ -1,6 +1,6 @@ --- name: abstract -description: Review or write an abstract (DITA short description) for a documentation module +description: Review or write an abstract (also called a short description) for a documentation module --- # Review or write abstract @@ -30,7 +30,7 @@ When reviewing or writing the abstract, follow these principles: - 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". +- When addressing the user, address them as "you". - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. - 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) diff --git a/.cursor/skills/abstract/references/concept.md b/.cursor/skills/abstract/references/concept.md index bfc1b293b40..a719452fcde 100644 --- a/.cursor/skills/abstract/references/concept.md +++ b/.cursor/skills/abstract/references/concept.md @@ -2,10 +2,8 @@ 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. +- Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "How is this knowledge useful to the user?" - 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 diff --git a/.cursor/skills/abstract/references/procedure.md b/.cursor/skills/abstract/references/procedure.md index d1047ee0317..2c9d07bcc9b 100644 --- a/.cursor/skills/abstract/references/procedure.md +++ b/.cursor/skills/abstract/references/procedure.md @@ -4,7 +4,6 @@ When the module has `:_mod-docs-content-type: PROCEDURE`, follow these rules for - 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. From 57f41ce619402555eab395b4472ebb649d883b36 Mon Sep 17 00:00:00 2001 From: Lena Ansorge Date: Wed, 20 May 2026 15:41:45 +0200 Subject: [PATCH 13/14] Apply suggestion from @aneta-petrova MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Aneta Petrová --- .cursor/skills/abstract/references/procedure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.cursor/skills/abstract/references/procedure.md b/.cursor/skills/abstract/references/procedure.md index 2c9d07bcc9b..467daf1ba0c 100644 --- a/.cursor/skills/abstract/references/procedure.md +++ b/.cursor/skills/abstract/references/procedure.md @@ -1,10 +1,10 @@ # 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. +- Use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", or "[Action] [what] to [why]". - When the abstract is too short, thin, or generic, add more information about why the task is beneficial. ## Examples of good abstracts From e6885925d711873791ccb170e97a780c27c31a5c Mon Sep 17 00:00:00 2001 From: Lena Ansorge Date: Wed, 20 May 2026 15:47:51 +0200 Subject: [PATCH 14/14] Apply suggestions from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Aneta Petrová Co-authored-by: Lena Ansorge --- .cursor/skills/abstract/references/concept.md | 2 +- .cursor/skills/abstract/references/procedure.md | 4 ++-- .cursor/skills/abstract/references/reference.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.cursor/skills/abstract/references/concept.md b/.cursor/skills/abstract/references/concept.md index a719452fcde..f680a287883 100644 --- a/.cursor/skills/abstract/references/concept.md +++ b/.cursor/skills/abstract/references/concept.md @@ -1,6 +1,6 @@ # Abstract instructions: concept modules -When the module has `:_mod-docs-content-type: CONCEPT`, follow these rules for the abstract (short description): +When the module is a concept module (is named `con_*.adoc` or includes `:_mod-docs-content-type: CONCEPT` as its first line), 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 "How is this knowledge useful to the user?" - Avoid using the short description to lead in or build up to a topic. diff --git a/.cursor/skills/abstract/references/procedure.md b/.cursor/skills/abstract/references/procedure.md index 467daf1ba0c..1da857e3d56 100644 --- a/.cursor/skills/abstract/references/procedure.md +++ b/.cursor/skills/abstract/references/procedure.md @@ -1,11 +1,11 @@ # Abstract instructions: procedure modules -When the module has `:_mod-docs-content-type: PROCEDURE`, follow these rules for the abstract (short description): +When the module is a procedure module (is named `proc_*.adoc` or includes `:_mod-docs-content-type: PROCEDURE` as its first line), follow these rules for the abstract (short description): - 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. - Use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", or "[Action] [what] to [why]". -- When the abstract is too short, thin, or generic, add more information about why the task is beneficial. +- When the abstract is too short or generic, add more information about why the task is beneficial. ## Examples of good abstracts diff --git a/.cursor/skills/abstract/references/reference.md b/.cursor/skills/abstract/references/reference.md index fdf547af8c3..dd18b49c14c 100644 --- a/.cursor/skills/abstract/references/reference.md +++ b/.cursor/skills/abstract/references/reference.md @@ -1,6 +1,6 @@ # Abstract instructions: reference modules -When the module has `:_mod-docs-content-type: REFERENCE`, follow these rules for the abstract (short description): +When the module is a reference module (is named `ref_*.adoc` or includes `:_mod-docs-content-type: REFERENCE` as its first line), follow these rules for the abstract (short description): - Briefly describe what the reference item does, what it is, or what it is used for.