RHIDP-12204: CQA 2.1 compliance for Adoption Insights in Red Hat Deve…#1876
Merged
themr0c merged 15 commits intoredhat-developer:mainfrom Mar 6, 2026
Merged
RHIDP-12204: CQA 2.1 compliance for Adoption Insights in Red Hat Deve…#1876themr0c merged 15 commits intoredhat-developer:mainfrom
themr0c merged 15 commits intoredhat-developer:mainfrom
Conversation
…loper Hub title Enhance Adoption Insights title for Adobe Experience Manager migration compliance: - Add short descriptions with [role="_abstract"] to all modules (50-300 chars) - Add .Procedure block titles to all procedure modules - Convert DITA-incompatible callouts to definition lists - Restructure proc-configure-adoption-insights with proper procedure steps - Add minimal content to empty stub proc-viewing-adoption-insights-card - Add CQA.md template for future compliance work All changes pass Vale DITA validation with 0 errors, 0 warnings. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Collaborator
|
Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1876/ @ 03/06/26 17:29:35 |
…ures Split proc-configure-adoption-insights.adoc into two focused procedures: - proc-enable-adoption-insights.adoc: Enable plugin after Developer Preview migration - proc-disable-adoption-insights.adoc: Disable the plugin when needed Changes: - Create proc-enable-adoption-insights.adoc with imperative title - Create proc-disable-adoption-insights.adoc with imperative title - Update assembly to include both new procedures - Delete original proc-configure-adoption-insights.adoc - Use proper ID format matching titles in lowercase - Use unordered list for single-step procedure (disable) - Restructure enable procedure with proper step continuation All changes pass Vale DITA validation with 0 errors, 0 warnings. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…edure Change proc-customize-adoption-insights.adoc to use ordered list for multi-step procedure: - Convert bullet points (*) to numbered steps (.) - Remove disable plugin step (now in separate proc-disable-adoption-insights.adoc) - Keep customization and RBAC configuration as two ordered steps Vale DITA validation passes with 0 errors, 0 warnings. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…iewing procedures Convert all multi-step viewing procedures from unordered lists (*) to ordered lists (.): - proc-viewing-active-users.adoc (3 steps) - proc-viewing-top-catalog-entities.adoc (2 steps) - proc-viewing-top-plugins.adoc (2 steps) - proc-viewing-top-templates.adoc (2 steps) - proc-viewing-total-number-of-users.adoc (2 steps) - proc-viewing-top-techdocs.adoc (2 steps) Single-step procedures remain unchanged with unordered list format. Vale DITA validation passes with 0 errors, 0 warnings. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Move descriptive content before .Procedure section to ensure clean DITA mapping: - Move data description bullets to introductory content before .Procedure - Add simple procedure step: navigate to view the Searches card - Ensures procedure section contains only a single list as required for DITA This fixes "Content other than a single list cannot be mapped to DITA tasks" issue. Vale DITA validation passes with 0 errors, 0 warnings. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…efinitions Convert field definition lists from unordered list with bold formatting to description lists: - proc-viewing-active-users.adoc: Returning users, New users - proc-viewing-total-number-of-users.adoc: Logged-in users, Licensed users - proc-viewing-top-catalog-entities.adoc: Name, Kind, Last used, Views - proc-viewing-top-plugins.adoc: Name, Trend, Views - proc-viewing-top-templates.adoc: Name, Mostly in use by, Executions - proc-viewing-top-techdocs.adoc: Name, Entity, Last used, Views Changed from: * *Term*: Definition To: Term:: Definition Vale DITA validation passes with 0 errors, 0 warnings. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Fabrice Flore-Thébault <ffloreth@redhat.com>
…ration-of-data-metrics Convert inline time range list to proper unordered list format for better readability: - Changed from inline comma-separated list to bulleted list - Time ranges: Today, Last week, Last month, Last 28 days (default), Last year, Date range... Vale DITA validation passes with 0 errors, 0 warnings. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…'like' Change "like components, APIs" to "such as components, APIs" to comply with Red Hat style guidelines. Vale validation now passes with 0 errors, 0 warnings (16 DITA suggestions about include directives can be ignored). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add comprehensive guidelines learned from Adoption Insights compliance work: **Procedure Module Style Guidelines:** - Title formatting (imperative form, no fluff, proper IDs) - Module ID naming convention - Multi-step vs single-step procedure formatting - Substep formatting with proper indentation - Content organization (one sentence per line) **Description Lists vs Unordered Lists:** - When to use description lists for field definitions - Avoid bold formatting in description list terms - Configuration settings formatting **File and Object References:** - Be specific: file vs config map vs ConfigMap - Proper terminology for Kubernetes objects **Lists in Procedures:** - Convert inline lists to proper list formatting **Additional Issues:** - DITA task mapping errors and fixes - Red Hat style violations (like vs such as) **Validation Commands:** - DITA validation (required) - Red Hat style validation (recommended) Updated success criteria to include Red Hat style validation. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
lhite8041
reviewed
Mar 6, 2026
Member
lhite8041
left a comment
lhite8041
left a comment
There was a problem hiding this comment.
These edits are pretty superficial. Note my suggestion in the prompt to include the new title requirement for procedure modules: change gerunds to imperative verbs.
themr0c
commented
Mar 6, 2026
themr0c
commented
Mar 6, 2026
themr0c
commented
Mar 6, 2026
themr0c
commented
Mar 6, 2026
themr0c
commented
Mar 6, 2026
themr0c
commented
Mar 6, 2026
…d update CQA.md Convert procedure module titles from gerund form to present-tense imperative form, update corresponding IDs to match titles without proc- prefix, rename files to match new titles, and update include statements in parent assembly. Changes: - Updated CQA.md with new learnings from RHIDP-12208: - Added section on removing "respective/respectively" with examples - Added section on splitting reference modules with nested sections - Added section on fixing broken xrefs after module splitting - Added build validation command and updated success criteria - Converted procedure titles from gerund to present-tense: - "Modifying the number of displayed records" → "Modify the number of displayed records" - "Viewing the Adoption Insights card" → "View the Adoption Insights card" - Updated module IDs to match titles (removed proc- prefix): - proc-modify-number-of-displayed-records → modify-the-number-of-displayed-records - proc-viewing-adoption-insights-card → view-the-adoption-insights-card - Renamed files to match new titles: - proc-modify-number-of-displayed-records.adoc → proc-modify-the-number-of-displayed-records.adoc - proc-viewing-adoption-insights-card.adoc → proc-view-the-adoption-insights-card.adoc - Updated include statements in assembly-adoption-insights.adoc to reference renamed files Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
IMPORTANT: Do Not Merge - To be merged by Docs Team Only
Version(s): RHDH 1.9+
Issue: https://issues.redhat.com/browse/RHIDP-12204
Preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1876/
Summary
This PR enhances the "Adoption Insights in Red Hat Developer Hub" title for CQA 2.1 compliance and Adobe Experience Manager (AEM) migration readiness.
All changes follow Red Hat modular documentation standards and DITA compatibility requirements.
Changes made
Content updates (16 procedure modules, 1 assembly):
[role="_abstract"]to all 16 modules (50-300 characters)proc-modify-number-of-displayed-records_{context}→modify-the-number-of-displayed-records_{context}proc-viewing-adoption-insights-card_{context}→view-the-adoption-insights-card_{context}proc-modify-number-of-displayed-records.adoc→proc-modify-the-number-of-displayed-records.adocproc-viewing-adoption-insights-card.adoc→proc-view-the-adoption-insights-card.adocDocumentation template (CQA.md):
Validation
Vale DITA validation results:
Vale Red Hat style results:
Related work
Commits
1bcb7fc8ad: CQA 2.1 compliance for Adoption Insights in Red Hat Developer Hub title44b2f75e6b: Split configure procedure into enable and disable procedures06147ca980: Convert unordered list to ordered list in customize procedurec14391436b: Convert unordered lists to ordered lists in multi-step viewing proceduresa59f9fcb7d: Fix DITA task mapping in proc-viewing-searchesaa8aa1c282: Convert unordered lists to description lists for field definitions40d725074b: Additional changesffd8473129: Convert time ranges to unordered list in proc-setting-duration-of-data-metrics27a8e46894: Fix Red Hat style compliance - use 'such as' instead of 'like'f4579d9c14: Update CQA.md with procedure formatting and style guidelines5844915442: Apply suggestions from code review42ee4a7712: Apply suggestion from @themr0cb7fb7d6b4b: Apply suggestions from code reviewc9121c1790: Apply suggestions from code reviewad87581561: Convert procedure titles from gerund to present-tense and update CQA.mdDetailed Changes
1. Assembly File
[role="_abstract"]2. New Procedure Modules
proc-enable-adoption-insights.adoc (new)
enable-the-adoption-insights-plugin_{context}proc-disable-adoption-insights.adoc (new)
disable-the-adoption-insights-plugin_{context}3. Updated Procedure Modules (13 files)
Configuration and Customization:
proc-customize-adoption-insights.adocUsage:
proc-using-adoption-insights.adocproc-setting-duration-of-data-metrics.adocViewing Procedures (8 files):
proc-view-the-adoption-insights-card.adoc(renamed from proc-viewing-adoption-insights-card.adoc)view-the-adoption-insights-card_{context}(changed fromproc-viewing-adoption-insights-card_{context})proc-viewing-active-users.adocproc-viewing-total-number-of-users.adocproc-viewing-top-catalog-entities.adocproc-viewing-top-templates.adocproc-viewing-top-techdocs.adocproc-viewing-top-plugins.adocproc-viewing-searches.adocDisplay Customization:
proc-modify-the-number-of-displayed-records.adoc(renamed from proc-modify-number-of-displayed-records.adoc)modify-the-number-of-displayed-records_{context}(changed fromproc-modify-number-of-displayed-records_{context})proc-filter-records-to-display-spec.adoc4. Documentation Template
5. Deleted Files
modules/observe/adoption-insights/proc-configure-adoption-insights.adoc(replaced by proc-enable and proc-disable)Test plan
CQA 2.1 Compliance Verification ✓
All acceptance criteria met:
[role="_abstract"]with 50-300 charactersThe "Adoption Insights in Red Hat Developer Hub" title is 100% CQA 2.1 compliant and ready for Adobe Experience Manager migration.
🤖 Generated with Claude Code