Cqa Titles Descriptions

CQA P8-P11: Titles and Short Descriptions

Parameters

| # | Parameter | Level | |---|-----------|-------| | P8 | Short descriptions are clear and describe why the user should read the content | Required | | P9 | Short descriptions: 50-300 chars, [role="_abstract"] present | Required | | P10 | Titles support short and descriptive forms (DITA) | Important | | P11 | Titles are brief, complete, and descriptive | Required |

Directory note

Some repos use modules/ instead of topics/ for content files. All topics/ references in this skill apply equally to modules/.

Step 1: Identify the docs repo

Ask the user for the path to their Red Hat modular documentation repository. Store as DOCS_REPO.

Step 2: P8 — Short description quality

Rule

The short description (the paragraph after [role="_abstract"]) maps to the DITA `` element. Per the DITA 1.3 spec, it "represents the purpose or theme of the topic" and is "intended to be used as a link preview and for search results."

Reference: https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/langRef/base/shortdesc.html

Content requirements by module type

| Module type | Short description must... | |-------------|--------------------------| | PROCEDURE | Explain WHAT the user can accomplish AND WHY (benefit/purpose). Not just "Do X." | | CONCEPT | Answer "What is this?" AND "Why do I care about this?" | | REFERENCE | Describe what the reference item does, what it is, or what it is used for | | ASSEMBLY | Explain what the user will accomplish by working through the modules (the user story reworded) |

Quality criteria

• Action-oriented: Tell the user what they can DO or UNDERSTAND
• Customer-centric: Written from the user's perspective, not the product's
• WHAT + WHY: State both what the topic covers and why it matters
• Technically accurate: Use correct product attributes ({prod-short}, {orch-name})
• Self-contained: Must work as a standalone snippet in search results — no context-dependent pronouns, no xrefs
• SEO/AI discoverable: Include keywords that users are likely to search on

Anti-patterns to flag

| Category | Pattern | Example | Fix | |----------|---------|---------|-----| | Self-referential | "This topic describes...", "This section covers...", "Learn how to..." | "This section describes how to configure OAuth." | "Configure OAuth to allow users to interact with Git repositories without re-entering credentials." | | Forward-referencing | "The following steps describe...", "the following methods:" | "The following steps describe how to create the required objects." | "Create the required objects for {prod-short} workspace configuration." | | Title repetition | Restates the title with "You can" | Title: "Listing workspaces" → SD: "You can list your workspaces." | Add the WHY: "List workspaces to monitor their status, resource usage, and running state." | | Missing WHY | States WHAT but not WHY | "Configure the Dashboard to display custom samples." | "Configure the Dashboard to display custom samples that demonstrate recommended devfile patterns for your team." | | Fallback framing | Positions content as secondary | "If you have trouble installing on the CLI, use the web console." | "Install {prod-short} through the {orch-name} web console for a guided, visual installation workflow." | | Sentence fragment | Ends with colon, flows into list | "Implement the following methods:" | "Implement the telemetry backend methods to collect and process workspace activity data." | | Links in abstract | Contains link:, xref:, or > | "See xref:topic[] for details." | Remove links. Links belong in .Additional resources. |

Good examples

• Procedure: "Configure OAuth to allow {prod-short} users to interact with remote Git repositories without re-entering credentials." (WHAT + WHY)
• Concept: "The {prod-short} server components manage multi-tenancy and workspace lifecycle. Understanding these components helps you troubleshoot issues and plan cluster capacity." (WHAT + WHY)
• Reference: "Customize the CheCluster Custom Resource by configuring its specification fields to control {prod-short} server, dashboard, gateway, and workspace components." (standalone, keyword-rich)
• Assembly: "Configure OAuth to allow {prod-short} users to interact with remote Git repositories without re-entering credentials." (user story reworded)

Scoring

| Score | Criteria | |-------|----------| | 4 | All short descriptions meet DITA quality standards: explain WHAT + WHY, no self-referential language, no title repetition, no fragments, self-contained for search results | | 3 | Most abstracts are good quality. Fewer than 15 have quality issues (missing WHY, title repetition, or minor patterns). | | 2 | Widespread quality failures: self-referential abstracts, title repetitions, or fragments in many files | | 1 | Short description quality not assessed or pervasive anti-patterns |

Step 3: P9 — Short description structural requirements

Rule

Every non-snippet module must have a [role="_abstract"] annotation followed by a prose paragraph within specific character limits.

Reference: "Rewrite for Impact: DITA short descriptions" (CCS presentation)

Structural checks

| Rule | Check | |------|-------| | [role="_abstract"] present | Every non-snippet file must have this annotation | | Blank line between title and abstract | At least one blank line must separate = Title from [role="_abstract"] | | No blank line between annotation and paragraph | [role="_abstract"] must be followed immediately by the abstract paragraph on the next line. A blank line disconnects them, making the abstract empty in DITA. | | Single paragraph | The abstract must be exactly one contiguous paragraph. No blank lines within it, no code blocks, no lists, no admonition blocks. A blank line must terminate the abstract before any subsequent body content. | | Character count 50-300 | Count raw AsciiDoc text. Attributes like {prod-short} count as their literal text (12 characters). "300 characters is between 42 and 75 words" (CCS presentation). | | Max 50 words | "A single, concise paragraph containing one or two sentences of no more than 50 words" (DITA 1.3 spec). |

Common structural violations

| Pattern | Problem | Fix | |---------|---------|-----| | Blank line after [role="_abstract"] | Abstract is empty in DITA conversion | Remove the blank line | | Abstract flows into code block | Code block becomes part of abstract (inflated character count) | Insert blank line after abstract paragraph | | Abstract flows into bullet list | List becomes part of abstract | Insert blank line after abstract paragraph | | Multiple paragraphs before first block title | Only the first paragraph is the shortdesc | Ensure only one paragraph between [role="_abstract"] and the next blank line | | Abstract exceeds 300 characters | Too long for link preview | Shorten to 1-2 sentences | | Abstract under 50 characters | Too short to be informative | Expand with WHAT + WHY |

Scoring

| Score | Criteria | |-------|----------| | 4 | All modules have [role="_abstract"], correct formatting (no blank line gap, single paragraph), all within 50-300 characters | | 3 | All annotations present. 1-5 files with character count violations (minor over/under). | | 2 | Multiple missing annotations or widespread structural violations | | 1 | Not assessed or pervasive missing abstracts |

Step 4: P10 — Title forms (DITA compatibility)

Rule

DITA supports three title forms per topic: short title (` with title-role="search"), navigation title (), and the primary title. In AsciiDoc, the = Title` heading serves all three purposes, so it must work in all contexts:

1. Search results — title must be self-descriptive without guide context
2. TOC navigation — title must be scannable at a glance
3. Full page heading — title must accurately describe the content

Check procedure

For each file in topics/ and assemblies/, verify the title works in all three contexts:

| Context | What to check | |---------|---------------| | Search | Would a user understand this title in isolation? (e.g., "Architecture" fails — "Dev Spaces architecture overview" works) | | Navigation | Is the title scannable in a TOC list? (too long titles hurt navigation) | | Page heading | Does the title accurately describe the content below? |

Scoring

| Score | Criteria | |-------|----------| | 4 | All titles work as search results, TOC entries, and page headings | | 3 | 1-3 titles that are ambiguous in search context (e.g., overly generic single-word titles) | | 2 | Multiple titles that fail in one or more contexts | | 1 | Not assessed or titles frequently misleading |

Step 5: P11 — Title quality

Rule

Titles must be brief, complete, and descriptive.

Reference:

• https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs
• https://ccs-internal-documentation.pages.redhat.com/peer-review/#_style

Check 1: Grammatical form

| Module type | Required form | Examples | |-------------|--------------|----------| | PROCEDURE | Imperative phrase (verb) | "Configure OAuth", "Install Dev Spaces" | | CONCEPT | Noun phrase (NOT gerund) | "Architecture overview", "Server components" | | REFERENCE | Noun phrase | "Supported platforms", "CheCluster fields" | | ASSEMBLY (task-based) | Imperative phrase | "Configure server components" | | ASSEMBLY (non-procedural) | Noun phrase | "Architecture overview" |

An assembly is task-based if it contains procedure modules.

Check 2: Title length

| Metric | Target | Flag | |--------|--------|------| | Word count | 3-11 words (resolved) | Flag titles under 3 words (if vague) or over 11 words | | Character count | 50-80 characters (resolved) | Titles under 50 chars acceptable if clear. Flag titles over 80 chars |

Attribute resolution for counting:

• {prod-short} = 3 words / 20 characters
• {prod} = 5 words / 35 characters
• {ocp} = 3 words / 30 characters
• {orch-name} = 1 word / 9 characters
• {devworkspace} = 2 words / 13 characters
• Backtick-quoted strings = 1 word each

When fixing long titles: Use shorter attribute forms ({prod-short} instead of {prod}, {orch-name} instead of {ocp}) to reduce word/character count while preserving meaning.

Check 3: Title quality rules

| Criterion | Rule | |-----------|------| | Sentence case | Only capitalize proper nouns, product names, and Kubernetes resource names | | No weak openers | Do not start concept titles with "About" or "Understanding" — use a noun phrase | | No vague titles | Single-word titles like "Architecture" lack context — add component/product name | | Correct article before attributes | {prod-short} (vowel "O") → "an {prod-short}". {prod} (consonant "R") → "a {prod}" | | No redundant product names | Do not hardcode names before attributes: "OpenShift {prod}" doubles "OpenShift" | | No possessives of brand names | "the OpenShift configuration" not "OpenShift's configuration" | | Concise phrasing | Remove filler words: "the code of applications running in" → "application code from" |

Acceptable exceptions

• Single Kubernetes resource names as subsection headings (== DevWorkspaceTemplate) when parent provides context
• Two-word titles like "Creating workspaces" or "Server components" that are clear and descriptive

Scoring

| Score | Criteria | |-------|----------| | 4 | All titles use correct grammatical form, are within length range, follow quality rules, and use sentence case | | 3 | 1-3 minor issues (borderline title length, one incorrect grammatical form) | | 2 | Multiple titles with wrong form, length violations, or quality issues | | 1 | Titles not checked or widespread violations |

Step 6: Verify

After fixing any violations, run Vale to ensure no new warnings were introduced:

cd "$DOCS_REPO"
vale assemblies/ topics/ titles/administration_guide/master.adoc titles/user_guide/master.adoc

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhatt-rh
• Source: abhatt-rh/redhat-docs-agent-tools
• License: Apache-2.0
• Homepage: https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.