Uploaded image for project: 'OpenShift Virtualization'
  1. OpenShift Virtualization
  2. CNV-68809

[CQA Stories] Review asciidoc formatting OVE

XMLWordPrintable

    • Quality / Stability / Reliability
    • 3
    • False
    • Hide

      None

      Show
      None
    • False
    • None
    • Yes
    • None

      Review and edit – if needed –  the below from the CQA analysis of the doc https://docs.redhat.com/en/documentation/red_hat_openshift_virtualization_engine/4/html/overview/index

       

       

      Quality Assessment: Content follows RH brand and style guidelines

      • Deviation Identified: The document uses :_module-type: CONCEPT in the metadata section of its modules.
      • Location: modules/ove-about.adoc and modules/ove-support.adoc.
      • Nature of Deviation: According to the modular documentation reference guide, this attribute name was updated in August 2023 from :_content-type: to :_mod-docs-content-type:. The _attributes/common-attributes.adoc file also shows the correct format as :_mod-docs-content-type: SNIPPET. The document uses a doubly outdated attribute name (:_module-type, which was updated to :_content-type: in August 2022 and then to :_mod-docs-content-type: in August 2023.
      • Deviation Identified: The document uses the product name {virt} without proper branding.
      • Location: modules/ove-about.adoc.
      • Nature of Deviation: Red Hat's product branding handbook states that products should be distinguished with technology icons and logos. The glossary also clarifies that {VirtProductName} is OpenShift Virtualization. A later reference correctly uses {virt-first} which expands to OpenShift® Virtualization. Using the shorthand {virt}
        is inconsistent with branding guidelines that prioritize clarity and the full product name on first use.

       

      ---------------------

       

      Quality Assessment: All Required/non-negotiable modular elements are present

      • Deviation Identified: The modules ove-about.adoc and ove-support.adoc are missing the required [id="<file-name>_\{context}"] anchor.
      • Location: modules/ove-about.adoc and modules/ove-support.adoc.
      • Nature of Deviation: The modular documentation checklist requires an ID in the format [id="<file-name>_\{context}"] for all modules and assemblies. The reference guide provides detailed instructions on creating this anchor for reusability. Both modules in the "OVE Overview" assembly are missing this element. They use [id="<file-name>_\{context}"] which is the correct format, but it's important to ensure the filename portion is accurate and the context variable is properly handled. A review of the source indicates they are [id="ove-about_\{context}"] and [id="ove-support_\{context}"], which follow the guideline.
      • Deviation Identified: The assembly ove-overview is missing the required conditional statements for nesting assemblies.
      • Location: ove-overview assembly file.
      • Nature of Deviation: The modular documentation checklist and reference guide state that assembly files must contain specific ifdef::context conditional statements at the top and bottom to manage the context variable when assemblies are nested. These statements are absent from the ove-overview assembly.

              Unassigned Unassigned
              rhn-support-sjess Sabrina Jess
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Created:
                Updated: