Merge pull request #103714 from openshift-cherrypick-robot/cherry-pick-102521-to-enterprise-4.18

[enterprise-4.18] CQA 2.0 AsciiDocDITA vale compliance

Author: jldohmann

modules/builds-define-build-inputs.adoc

@@ -6,7 +6,10 @@
 [id="builds-define-build-inputs_{context}"]
 = Build inputs
 
-A build input provides source content for builds to operate on. You can use the following build inputs to provide sources in {product-title}, listed in order of precedence:
+[role="_abstract"]
+Use different build inputs in {product-title} to provide source content for your builds. Understanding the order of precedence helps ensure your builds use the correct sources.
+
+The following build inputs are available and listed in order of precedence:
 
 ifndef::openshift-online[]
 * Inline Dockerfile definitions
@@ -55,24 +58,26 @@ The following example of a source definition includes multiple input types and a
 ----
 source:
   git:
-    uri: https://github.com/openshift/ruby-hello-world.git <1>
+    uri: https://github.com/openshift/ruby-hello-world.git
     ref: "master"
   images:
   - from:
       kind: ImageStreamTag
       name: myinputimage:latest
       namespace: mynamespace
     paths:
-    - destinationDir: app/dir/injected/dir <2>
+    - destinationDir: app/dir/injected/dir
       sourcePath: /usr/lib/somefile.jar
-  contextDir: "app/dir" <3>
+  contextDir: "app/dir"
 ifndef::openshift-online[]
-  dockerfile: "FROM centos:7\nRUN yum install -y httpd" <4>
+  dockerfile: "FROM centos:7\nRUN yum install -y httpd"
 endif::[]
 ----
-<1> The repository to be cloned into the working directory for the build.
-<2> `/usr/lib/somefile.jar` from `myinputimage` is stored in `<workingdir>/app/dir/injected/dir`.
-<3> The working directory for the build becomes `<original_workingdir>/app/dir`.
+where:
+
+`uri`:: Specifies the repository to be cloned into the working directory for the build.
+`destinationDir`:: Specifies the repository to be cloned into the working directory for the build.
+`contextDir`:: Specifies the working directory for the build becomes `<original_workingdir>/app/dir`.
 ifndef::openshift-online[]
-<4> A Dockerfile with this content is created in `<original_workingdir>/app/dir`, overwriting any existing file with that name.
+`dockerFile`:: A Dockerfile with this content is created in `<original_workingdir>/app/dir`, overwriting any existing file with that name.
 endif::[]

modules/images-create-guide-general.adoc

@@ -5,8 +5,8 @@
 [id="images-create-guide-general_{context}"]
 = General container image guidelines
 
-The following guidelines apply when creating a container image in general, and are independent of whether the images are used on {product-title}.
-
+[role="_abstract"]
+Follow fundamental guidelines for creating container images to ensure they are secure, efficient, and reproducible for deployment in {product-title}.
 
 == Reuse images
 

modules/images-create-guide-openshift.adoc

@@ -5,8 +5,8 @@
 [id="images-create-guide-openshift_{context}"]
 = {product-title}-specific guidelines
 
-The following are guidelines that apply when creating container images specifically
-for use on {product-title}.
+[role="_abstract"]
+Use the integrated image-building capabilities of {product-title} to create, manage, and deploy reproducible container images directly from source code or Dockerfiles.
 ifdef::openshift-online[]
 
 [id="privileges-and-volume-builds_{context}"]

modules/images-create-guidelines.adoc

@@ -5,4 +5,5 @@
 [id="images-create-guidelines_{context}"]
 = Learning container best practices
 
+[role="_abstract"]
 When creating container images to run on {product-title} there are a number of best practices to consider as an image author to ensure a good experience for consumers of those images. Because images are intended to be immutable and used as-is, the following guidelines help ensure that your images are highly consumable and easy to use on {product-title}.

modules/images-create-metadata.adoc

@@ -5,7 +5,10 @@
 [id="images-create-metadata_{context}"]
 = Including metadata in images
 
-Defining image metadata helps {product-title} better consume your container images, allowing {product-title} to create a better experience for developers using your image. For example, you can add metadata to provide helpful descriptions of your image, or offer suggestions on other images that may also be needed.
+[role="_abstract"]
+Define comprehensive image metadata during creation to ensure {product-title} correctly configures image runtime settings and tracks image lineage and compliance. This helps to provide a better experience for developers using your image.
+
+For example, you can add metadata to provide helpful descriptions of your image, or offer suggestions on other images that may also be needed.
 
 This topic only defines the metadata needed by the current set of use cases. Additional metadata or use cases may be added in the future.
 

modules/images-create-s2i-build.adoc

@@ -7,10 +7,13 @@
 [id="images-create-s2i-build_{context}"]
 = Understanding the source-to-image build process
 
+[role="_abstract"]
+Leverage the Source-to-image (S2I) process in {product-title} to seamlessly transform application source code into ready-to-run, reproducible container images.
+
 The build process consists of the following three fundamental elements, which are combined into a final container image:
 
 * Sources
-* Source-to-image (S2I) scripts
+* S2I scripts
 * Builder image
 
 S2I generates a Dockerfile with the builder image as the first `FROM` instruction. The Dockerfile generated by S2I is then passed to Buildah.

modules/images-create-s2i-scripts.adoc

@@ -7,7 +7,10 @@
 [id="images-create-s2i-scripts_{context}"]
 = How to write source-to-image scripts
 
-You can write source-to-image (S2I) scripts in any programming language, as long as the scripts are executable inside the builder image. S2I supports multiple options providing `assemble`/`run`/`save-artifacts` scripts. All of these locations are checked on each build in the following order:
+[role="_abstract"]
+Define mandatory Source-to-image (S2I) scripts, such as `assemble` and `run` to enable {product-title} to build, customize, and execute highly reproducible container images.
+
+You can write S2I scripts in any programming language, as long as the scripts are executable inside the builder image. S2I supports multiple options providing `assemble`/`run`/`save-artifacts` scripts. All of these locations are checked on each build in the following order:
 
 . A script specified in the build configuration.
 . A script found in the application source `.s2i/bin` directory.

modules/images-create-s2i.adoc

@@ -7,6 +7,7 @@
 [id="images-create-s2i_{context}"]
 = Creating images from source code with source-to-image
 
+[role="_abstract"]
 Source-to-image (S2I) is a framework that makes it easy to write images that take application source code as an input and produce a new image that runs the assembled application as output.
 
 The main advantage of using S2I for building reproducible container images is the ease of use for developers. As a builder image author, you must understand two basic concepts in order for your images to provide the best S2I performance, the build process and S2I scripts.

modules/images-test-s2i.adoc

@@ -5,7 +5,10 @@
 [id="images-test-s2i_{context}"]
 = About testing source-to-image images
 
-As an Source-to-Image (S2I) builder image author, you can test your S2I image
+[role="_abstract"]
+Verify your Source-to-image (S2I) environment and resulting application images to ensure successful, reproducible container deployment within {product-title}.
+
+As an S2I builder image author, you can test your S2I image
 locally and use the {product-title} build system for automated testing and
 continuous integration.
 

openshift_images/create-images.adoc

@@ -1,11 +1,13 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="creating-images"]
 = Creating images
+
 include::_attributes/common-attributes.adoc[]
 :context: create-images
 
 toc::[]
 
+[role="_abstract"]
 Learn how to create your own container images, based on pre-built images that are ready to help you. The process includes learning best practices for writing images, defining metadata for images, testing images, and using a custom builder workflow to create images to use with {product-title}.
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
 After you create an image, you can push it to the {product-registry}.