CQA 2.1 compliance: Upgrading Red Hat Developer Hub

Task

Fix the Upgrading Red Hat Developer Hub title content to be compliant with CQA 2.1 – Content Quality Assessment.

Background

CCS is migrating documentation to Adobe Experience Manager. All the content must be compatible with DITA and AEM before migrating. The CQA 2.1 – Content Quality Assessment defines requirements to meet: https://docs.google.com/spreadsheets/d/1wF_NUWXBJaYsaXp8Dn6TQOx9gD45NCqNxaPkXhYN-zI/edit?gid=503904153#gid=503904153 

Dependencies and Blockers

Acceptance Criteria

Asciidoc

• Content passes this Vale asciidoctor-dita-vale tool check with no errors or warnings.
  The AsciiDocDITA tool identifies markup that does not have a direct equivalent in DITA 1.3. See the readme for details about specific issues that it finds. Note: The AsciiDocDITA tool is updated frequently.
• Assemblies should contain only an introductory section, which can be one or more paragraphs, and include statements. You can also have an Additional resources section at the end of the assembly, after all of the includes.
  DITA maps do not accept text between include statements for modules.

Modularization

• Content is modularized
• Modules use the official templates:

• Concept
• Procedure
• Reference

• All Required/non-negotiable modular elements are present.
  See (WIP) Modular documentation templates checklist

• Assemblies use the official template.
  Assemblies are one user story.
• Content is not deeply nested in the TOC (recommended: no more than 3 levels).
  Note: For migration, you can start counting levels where your content starts, not including categories and the repetitive book titles that Pantheon generates.

Titles and short descriptions

• Modules and assemblies start with a clear short description. A short description:

• Describes why the user should read the content
• Uses concise language that will be used as a link preview or for summaries in search results
• Includes keywords that users are likey to search on for SEO and AI
• Must not include self referential language ("This document describes...")
  See the following doc about shortdesc in DITA: 
  https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/langRef/base/shortdesc.html 

• In asciidoc, short descriptions must be:

• be a single paragraph between 50 and 300 characters
• Introduced with [role="_abstract"]
• Include a blank line between the level 0 (=) title and the short description in asciidoc
  Note: See Rewrite for Impact: DITA short descriptions

• Titles are brief, complete, and descriptive.
  Use the following guidelines for titles:
  - Procedure modules in the Modular documentation reference guide

• Peer review checklist for style in Red Hat peer review guide for technical documentation

Procedures

• If a procedures includes prerequisites:

• Use the Prerequisites label
• Use consistent formatting
  Do not exceed 10 prerequisites.
  Do not include steps in prerequisites.

Editorial

• Content is grammatically correct and follows rules of American English grammar
• Information is conveyed using the correct content type

URLs and links

• No broken links
• Redirects (if needed) are in place and work correctly

Legal and Branding

• Official product names are used
• Includes appropriate, legal-approved disclaimers for Technology Preview and Developer Preview features/content. You can use snippets for these disclaimers in assembly files. They will resolve appropriately during migration.