From cqa-tools
Audits documentation tables and images for CQA Q19 (excessive screenshots), Q21 (captions and headers), Q22 (alt text). Scans topics/ dirs for issues using grep and glob.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin cqa-toolsThis skill is limited to using the following tools:
| # | Parameter | Level |
Reviews Red Hat documentation for WCAG accessibility compliance: alt text for images/icons, no color-only info, no directional language, descriptive links, proper tables, and heading nesting. Use for a11y checks on Red Hat docs.
Assesses CQA parameters P8-P11 for titles and short descriptions in Red Hat modular documentation, checking clarity, character limits, DITA conventions, and quality criteria.
Provides checklists, metrics, scoring, and grep-based detection patterns for auditing README, API, and architecture documentation quality.
Share bugs, ideas, or general feedback.
| # | Parameter | Level |
|---|---|---|
| Q19 | No excessive use of screen images | Important |
| Q21 | Tables have captions and are clearly labeled | Important |
| Q22 | Images have captions and meaningful alt text | Important |
Some repos use modules/ instead of topics/ for content files. All topics/ references in this skill apply equally to modules/. The automation scripts accept --scan-dirs to override the default scan directories.
Screen captures are useful when they:
Screen captures are less successful when:
image:: references have meaningful alt text (not empty [] or generic "screenshot")images/ not referenced by any topic)Every table must have:
.Title caption (line starting with . immediately before [cols=...] or |===)options="header" attribute (or [%header,...]) to mark the header row.Supported platforms
[cols="1,1",options="header"]
|===
| Platform | Version
| OpenShift
| 4.15+
|===
|=== table delimiters in topics/ and assemblies/|===, check that a .Title caption exists on a preceding line (before [cols=...] or directly before |===)options="header" or [%header,...] is present in the table attribute|=== is a header row (column labels, not data)== subsection headings may lack .Title captions because the heading seems to serve as the label. Both are needed: == is a section heading, .Title is the table caption (maps to <title> in DITA).[cols=...] attribute may omit options="header" — add [cols="1,1",options="header"] before |===.. step text with + continuation) still need captions.This parameter covers four aspects of image quality (Usability checklist):
[] or generic "screenshot", "image")Every image:: must have meaningful alt text in brackets:
image::architecture/overview.png[Dev Spaces architecture overview]
Empty brackets [] or generic alt text ("screenshot", "image") are violations. Alt text should describe the content or purpose of the image, not just its format.
Images in concept files should have .Title block title captions on the line before the image:: directive:
.High-level architecture with the DevWorkspace operator
image::architecture/devspaces-interacting-with-devworkspace.png[High-level architecture diagram]
The block title maps to <title> in DITA output and serves as the figure caption in rendered documentation.
When block titles are required:
.Additional resources or standalone image blocksWhen block titles are acceptable to omit:
+ continuation where the step text provides the caption context (e.g., ". Create a workspace on the Dashboard and choose IntelliJ IDEA Ultimate:" followed by screenshot)Every image must be clearly explained by surrounding text:
image:: directives in topics/ (or modules/) and assemblies/.adoc file containing each image:: directive actually exists in the repo — skip any references found in files that are not present on disk (e.g., files from unresolved includes, other branches, or orphaned references). Do NOT flag alt text issues for files that do not exist in the repo.:imagesdir: if set, otherwise relative to the .adoc file). Skip and note any missing image files — these are broken references, not alt text issues.[], [screenshot], [image]).Title block caption exists on the preceding line.Title captions should use sentence case, no trailing periodimage:: across the repo may find references in .adoc files that do not exist on the current branch, are not included from any assembly, or are leftover from a different build. Always verify the .adoc file and the image file both exist before reporting an issue..Title captions — inconsistent with other concept images in the repoSee scoring-guide.md.