Changes to buider doc

Changes to first parts of Execution Environments doc

Improve EE documentation

https://issues.redhat.com/browse/AAP-24985

downstream/assemblies/builder/assembly-definition-file-breakdown.adoc

@@ -4,7 +4,7 @@
 
 A definition file is required for building {ExecEnvName} with {Builder}, because it specifies the content that is included in the {ExecEnvNameSing} container image.
 
-The following sections breaks down the different parts of a definition file.
+The following sections break down the different parts of a definition file.
 
 include::builder/ref-build-args-base-image.adoc[leveloffset=+1]
 //include::builder/con-ansible-config-file-path.adoc[leveloffset=+1]

downstream/assemblies/builder/assembly-using-builder.adoc

@@ -6,6 +6,7 @@
 
 include::builder/con-why-builder.adoc[leveloffset=+1]
 include::builder/proc-installing-builder.adoc[leveloffset=+1]
+include::builder/ref-content-needed-for-builder.adoc[leveloffset=+1]
 include::platform/con-building-an-execution-environment-in-a-disconnected-environment.adoc[leveloffset=+1]
 include::builder/con-building-definition-file.adoc[leveloffset=+1]
 

downstream/modules/builder/con-about-ee.adoc

@@ -4,13 +4,17 @@
 
 [role="_abstract"]
 
-All automation in {PlatformName} runs on container images called {ExecEnvName}.
+All automation in {PlatformName} runs on Podman container images called {ExecEnvName}.
 {ExecEnvNameStart} create a common language for communicating automation dependencies, and offer a standard way to build and distribute the automation environment.
 
+Red Hat provides supported {ExecEnvShort}s link:https://catalog.redhat.com/search?gs&q=execution%20environments&searchType=containers[here].
+
 An {ExecEnvNameSing} should contain the following:
 
 * Ansible Core 2.15 or later
 * Python 3.8-3.11
 * {Runner}
 * Ansible content collections and their dependencies
 * System dependencies
+
+

downstream/modules/builder/con-building-definition-file.adoc

@@ -2,7 +2,8 @@
 
 = Building a definition file
 
-After you install {Builder}, you can create a definition file that {Builder} uses to create your {ExecEnvNameSing} image. {Builder} makes an {ExecEnvNameSing} image by reading and validating your definition file, then creating a `Containerfile`, and finally passing the `Containerfile` to Podman, which then packages and creates your {ExecEnvNameSing} image. The definition file that you create must be in `yaml` format and contain different sections. The default definition filename, if not provided, is `execution-environment.yml`. For more information on the parts of a definition file, see xref:assembly-definition-file-breakdown[Breakdown of definition file content].
+After you install {Builder}, you can create a definition file that defines what {Builder} uses to create your {ExecEnvNameSing} image. {Builder} makes an {ExecEnvNameSing} image by reading and validating your definition file, then creating a `Containerfile`, and finally passing the `Containerfile` to Podman, which then packages and creates your {ExecEnvNameSing} container image. 
+The definition file that you create must be in `yaml` format and contain different sections. The default definition filename, if not provided, is `execution-environment.yml`. For more information on the parts of a definition file, see xref:assembly-definition-file-breakdown[Breakdown of definition file content].
 
 The following is an example of a version 3 definition file. Each definition file must specify the major version number of the {Builder} feature set it uses. If not specified, {Builder} defaults to version 1, making most new features and definition keywords unavailable.
 

downstream/modules/builder/con-why-builder.adoc

@@ -4,4 +4,4 @@
 
 Before {Builder} was developed, {PlatformName} users could run into dependency issues and errors when creating custom virtual environments or containers that included all of the required dependencies installed.
 
-Now, with {Builder}, you can easily create a customizable {ExecEnvName} definition file that specifies the content you want included in your {ExecEnvName} such as Ansible Core, Python, Collections, third-party Python requirements, and system level packages. This allows you to fulfill all of the necessary requirements and dependencies to get jobs running.
+Now, with {Builder}, you can easily create a customizable {ExecEnvName} definition file that specifies the content you want included in your {ExecEnvName} such as Ansible Core, Python, Collections, third-party Python requirements, and system level packages. This enables you to fulfill all of the necessary requirements and dependencies to get jobs running.

downstream/modules/builder/con-why-ee.adoc

@@ -1,6 +1,6 @@
 [id="con-why-ee"]
 
-= Why use {ExecEnvName}?
+= Why {ExecEnvName}?
 
 With {ExecEnvName}, {PlatformName} has transitioned to a distributed architecture by separating the control plane from the execution plane.
 Keeping automation execution independent of the control plane results in faster development cycles and improves scalability, reliability, and portability across environments.
@@ -10,7 +10,7 @@ In addition to speed, portability, and flexibility, {ExecEnvName} provide the fo
 
 * They ensure that automation runs consistently across multiple platforms and make it possible to incorporate system-level dependencies and collection-based content.
 * They give {PlatformName} administrators the ability to provide and manage automation environments to meet the needs of different teams.
-* They allow automation to be easily scaled and shared between teams by providing a standard way of building and distributing the automation environment.
-* They enable automation teams to define, build, and update their automation environments themselves.
+* They enable automation to be easily scaled and shared between teams by providing a standard way of building and distributing the automation environment.
+* {ExecEnvNameStart}s enable automation teams to define, build, and update their automation environments themselves.
 * {ExecEnvNameStart} provide a common language to communicate automation dependencies.
 

downstream/modules/builder/proc-installing-builder.adoc

@@ -3,8 +3,9 @@
 = Installing {Builder}
 
 .Prerequisites
-* You have installed the Podman container runtime.
-* You have valid subscriptions attached on the host. Doing so allows you to access the subscription-only resources needed to install `ansible-builder`, and ensures that the necessary repository for `ansible-builder` is automatically enabled. See link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/access_management_and_authentication/index#proc-attaching-subscriptions[Attaching your Red Hat {PlatformNameShort} subscription] for more information. 
+* You have valid subscriptions attached on the host. 
+Doing so allows you to access the subscription-only resources needed to install `ansible-builder`, and ensures that the necessary repository for `ansible-builder` is automatically enabled. 
+See link:{URLCentralAuth}/assembly-gateway-licensing#proc-attaching-subscriptions[Attaching your Red Hat {PlatformNameShort} subscription] for more information. 
 
 .Procedure
 

downstream/modules/builder/ref-build-args-base-image.adoc

@@ -2,7 +2,7 @@
 
 = Build args and base image
 
-The `build_arg_defaults` section of the definition file is a dictionary whose keys can provide default values for arguments to {Builder}. See the following table for a list of values that can be used in `build_arg_defaults`:
+The `build_arg_defaults` section of the definition file is a dictionary whose keys can provide default values for arguments to {Builder}. The following table lists values that can be used in `build_arg_defaults`:
 
 [cols="a,a"]
 |===
@@ -16,6 +16,6 @@ The `build_arg_defaults` section of the definition file is a dictionary whose ke
 
 |===
 
-The values given inside `build_arg_defaults` will be hard-coded into the `Containerfile`, so these values will persist if `podman build` is called manually.
+The values given inside `build_arg_defaults` are hard-coded into the `Containerfile`, so these values persist if `podman build` is called manually.
 
-NOTE: If the same variable is specified in the CLI `--build-arg` flag, the CLI value will take higher precedence.
+NOTE: If the same variable is specified in the CLI `--build-arg` flag, the CLI value takes higher precedence.

downstream/modules/builder/ref-content-needed-for-builder.adoc

@@ -0,0 +1,19 @@
+[id="ref-content-needed-for-builder"]
+
+= Content needed for an execution environment 
+
+Ansible-builder is used to create an {ExecEnvShort}.
+
+An {ExecEnvShort} must contain:
+
+* Ansible
+* Ansible Runner
+* Ansible Collections
+* Python and system dependencies of:
+** modules or plugins in collections
+** content in ansible-base
+**custom user needs
+
+Building a new {ExecEnvShort} involves a definition that specifies which content you want to include in your {ExecEnvShort}, such as collections, Python requirements, and system-level packages. 
+The definition must be a `.yml` file
+The content from the output generated from migrating to {ExecEnvShort}s has some of the required data that can be piped to a file or pasted into this definition file.

downstream/modules/platform/con-building-an-execution-environment-in-a-disconnected-environment.adoc

@@ -8,20 +8,22 @@
 
 Creating execution environments for {PlatformNameShort} is a common task which works differently in disconnected environments. When building a custom {ExecEnvShort}, the ansible-builder tool defaults to downloading content from the following locations on the internet:
 
-* Red Hat {HubNameStart} ({Console}) or {Galaxy} (galaxy.ansible.com) for any Ansible content collections added to the {ExecEnvShort} image.
+* Red Hat {HubNameStart} (`{Console}`) or {Galaxy} (`galaxy.ansible.com`) for any Ansible content collections added to the {ExecEnvShort} image.
 
-* PyPI (pypi.org) for any python packages required as collection dependencies.
+* PyPI (`pypi.org`) for any python packages required as collection dependencies.
 
 * RPM repositories such as the RHEL or UBI repositories (cdn.redhat.com) for adding or updating RPMs to the {ExecEnvShort} image, if needed. 
 
-* registry.redhat.io for access to the base container images.
+* `registry.redhat.io` for access to the base container images.
 
 Building an {ExecEnvShort} image in a disconnected environment requires mirroring content from these locations.
 For information about importing collections from {Galaxy} or {HubName} into a {PrivateHubName}, see link:{URLHubManagingContent}/managing-collections-hub#proc-import-collection[Importing an automation content collection in {HubName}] .
 
-Mirrored PyPI content once transferred into the disconnected network can be made available by using a web server or an artifact repository such as Nexus. The RHEL and UBI repository content can be exported from an internet-facing Red Hat Satellite Server, copied into the disconnected environment, then imported into a disconnected Satellite so it is available for building custom {ExecEnvShort}s. See link:{BaseURL}/red_hat_satellite/{SatelliteVers}/html-single/installing_satellite_server_in_a_disconnected_network_environment/index#iss_export_sync_in_an_air_gapped_scenario[ISS Export Sync in an Air-Gapped Scenario] for details.
+Mirrored PyPI content once transferred into the disconnected network can be made available by using a web server or an artifact repository. The RHEL and UBI repository content can be exported from an internet-facing Red Hat Satellite Server, copied into the disconnected environment, then imported into a disconnected Satellite so it is available for building custom {ExecEnvShort}s. See link:{BaseURL}/red_hat_satellite/{SatelliteVers}/html-single/installing_satellite_server_in_a_disconnected_network_environment/index#iss_export_sync_in_an_air_gapped_scenario[ISS Export Sync in an Air-Gapped Scenario] for details.
 
-The default base container image, ee-minimal-rhel8, is used to create custom {ExecEnvShort} images and is included with the bundled installer. This image is added to the {PrivateHubName} at install time. If a different base container image such as ee-minimal-rhel9 is required, it must be imported to the disconnected network and added to the {PrivateHubName} container registry.
+The default base container image, `ee-minimal-rhel8`, is used to create custom {ExecEnvShort} images and is included with the bundled installer. 
+This image is added to the {PrivateHubName} at install time. 
+If a different base container image such as `ee-minimal-rhel9` is required, it must be imported to the disconnected network and added to the {PrivateHubName} container registry.
 
 Once all of the prerequisites are available on the disconnected network, the ansible-builder command can be used to create custom {ExecEnvShort} images.
 

downstream/titles/builder/master.adoc

@@ -9,7 +9,7 @@ include::attributes/attributes.adoc[]
 // Book Title
 = Creating and using execution environments
 
-Use {ExecEnvshort} builder to create consistent and reproducible containers for your {PlatformName} needs.
+Use the {ExecEnvshort} builder (ansible-builder) to create consistent and reproducible containers for your {PlatformName} needs.
 
 include::{Boilerplate}[]