From cqa-tools
Assesses CQA parameters P8-P11 for titles and short descriptions in Red Hat modular documentation, checking clarity, character limits, DITA conventions, and quality criteria.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin cqa-toolsThis skill is limited to using the following tools:
| # | Parameter | Level |
Assesses CQA P2-P7 modularization in Red Hat AsciiDoc docs: assembly structure without rendered text between includes, module prefixes, templates, required elements, nesting depth.
Rewrites short descriptions in AsciiDoc files for clarity, conciseness, and DITA compliance. Use when fixing abstracts, improving summaries, or enhancing short descriptions in topics.
Reviews AsciiDoc (.adoc) files for Red Hat modular documentation compliance: module types (concept, procedure, reference), assembly structure, anchor IDs with _{context}, context variables, and include directives.
Share bugs, ideas, or general feedback.
| # | 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, long, and descriptive forms (DITA) | Important |
| P11 | Titles are brief, complete, and descriptive | Required |
Some repos use modules/ instead of topics/ for content files. All topics/ references in this skill apply equally to modules/.
Ask the user for the path to their Red Hat modular documentation repository. Store as DOCS_REPO.
The short description (the paragraph after [role="_abstract"]) maps to the DITA <shortdesc> 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."
| 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) |
{prod-short}, {orch-name})| 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. |
| 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 |
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)
| 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). |
| 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 |
| 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 |
DITA supports three title forms per topic: short title (<titlealt> with title-role="search"), navigation title (<navtitle>), and the primary title. In AsciiDoc, the = Title heading serves all three purposes, so it must work in all contexts:
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? |
| 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 |
Titles must be brief, complete, and descriptive.
Reference:
| 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.
| 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 charactersWhen 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.
| 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" |
== DevWorkspaceTemplate) when parent provides context| 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 |
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