CQA changes for getting Started with playbooks (ansible#5070)

ianf77 · KylaF8 · commit 922cf6417abf · 2025-11-18T11:45:29.000Z
CQA checks: Getting Started with Playbooks https://issues.redhat.com/browse/AAP-58656
diff --git a/downstream/assemblies/playbooks/assembly-intro-to-playbooks.adoc b/downstream/assemblies/playbooks/assembly-intro-to-playbooks.adoc
@@ -4,12 +4,15 @@
 
 = Introduction
 
+[ role="_abstract"]
 An Ansible Playbook is a blueprint for automation tasks, which are actions executed with limited manual effort across an inventory of solutions. 
 Playbooks tell Ansible what to do on which devices.
-Instead of manually applying the same action to hundreds or thousands of similar technologies across IT environments, executing a playbook automatically completes the same action for the specified type of inventory—such as a set of routers. 
 
-Playbooks are regularly used to automate IT infrastructure—such as operating systems and Kubernetes platforms—networks, security systems, and code repositories like GitHub.
-You can use playbooks to program applications, services, server nodes, and other devices, without the manual overhead of creating everything from scratch.
+Instead of manually applying the same action to many similar technologies across IT environments, executing a playbook automatically completes the same action for the specified type of inventory, such as a set of routers. 
+
+Playbooks are regularly used to automate IT infrastructure, such as operating systems, Kubernetes platforms, networks, security systems, and code repositories such as GitHub.
+
+You can use playbooks to program applications, services, server nodes, and other devices, without the effort of creating everything from scratch.
 Playbooks, and the conditions, variables, and tasks within them, can be saved, shared, or reused indefinitely. 
 This makes it easier for you to codify operational knowledge and ensure that the same actions are performed consistently.
 
diff --git a/downstream/assemblies/playbooks/assembly-networking-playbook.adoc b/downstream/assemblies/playbooks/assembly-networking-playbook.adoc
@@ -2,7 +2,10 @@
 
 [id="assembly-networking-playbook"]
 
-= Use a Playbook to establish a connection to a managed node
+= Use a playbook to establish a connection to a managed node
+
+[role="_abstract"]
+Learn how to create and run a simple Ansible Playbook that connects to a network device, gathers facts, and displays them.
 
 To confirm your credentials, you can connect to a network device manually and retrieve its configuration. Replace the sample user and device name with your real credentials. 
 
diff --git a/downstream/assemblies/playbooks/assembly-playbook-practical-example.adoc b/downstream/assemblies/playbooks/assembly-playbook-practical-example.adoc
@@ -4,8 +4,8 @@
 
 = A practical example of an Ansible Playbook
 
+[role="_abstract"]
 Ansible can communicate with many different device classifications, from cloud-based REST APIs, to Linux and Windows systems, networking hardware, and much more. 
-
 The following is a sample of two Ansible modules automatically updating two types of servers.
 
 include::playbooks/ref-playbook-execution.adoc[leveloffset=+1]
diff --git a/downstream/modules/playbooks/proc-build-an-inventory.adoc b/downstream/modules/playbooks/proc-build-an-inventory.adoc
@@ -4,33 +4,35 @@
 
 = Building an inventory
 
+[role="_abstract"]
 Inventories organize managed nodes in centralized files that provide Ansible with system information and network locations. Using an inventory file, Ansible can manage a large number of hosts with a single command.
-To complete the following steps, you need the IP address or fully qualified domain name (FQDN) of at least one host system. For demonstration purposes, the host could be running locally in a container or a virtual machine. 
 
-You must also ensure that your public SSH key is added to the `authorized_keys` file on each host.
+.Prerequisites
+* To complete the following steps, you need the IP address or fully qualified domain name (FQDN) of at least one host system. For demonstration purposes, the host could be running locally in a container or a virtual machine. 
+* You must also ensure that your public SSH key is added to the `authorized_keys` file on each host.
 Use the following procedure to build an inventory.
 
 .Procedure
-Create a file named `inventory.ini` in the `ansible_quickstart` directory that you created.
-Add a new `[myhosts]` group to the inventory.ini file and specify the IP address or fully qualified domain name (FQDN) of each host system.
-
+. Create a file named `inventory.ini` in the `ansible_quickstart` directory that you created.
+. Add a new `[myhosts]` group to the inventory.ini file and specify the IP address or fully qualified domain name (FQDN) of each host system.
++
 ----
 [myhosts]
 192.0.2.50
 192.0.2.51
 192.0.2.52
 ----
 
-Verify your inventory, using:
-
+. Verify your inventory, using:
++
 `ansible-inventory -i inventory.ini --list`
 
-Ping the `myhosts` group in your inventory, using:
-
+. Ping the `myhosts` group in your inventory, using:
++
 'ansible myhosts -m ping -i inventory.ini`
-
++
 Pass the `-u` option with the Ansible command if the username is different on the control node and the managed node(s).
-
++
 ----
 192.0.2.50 | SUCCESS => {
     "ansible_facts": {
@@ -54,6 +56,6 @@ Pass the `-u` option with the Ansible command if the username is different on th
     "ping": "pong"
 }
 ----
-
++
 You have successfully built an inventory.
 
diff --git a/downstream/modules/playbooks/proc-creating-a-playbook.adoc b/downstream/modules/playbooks/proc-creating-a-playbook.adoc
@@ -4,7 +4,8 @@
 
 = Creating your first playbook
 
-Use the following procedure to create a playbook that pings your hosts and prints a “Hello world” message.
+[role="_abstract"]
+Learn how to create a playbook that pings your hosts and prints a “Hello world” message.
 
 .Procedure
 . Create a file named `playbook.yaml` in your `ansible_quickstart` directory, with the following content:
@@ -54,7 +55,7 @@ PLAY RECAP *********************************************************************
 192.0.2.51: ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
 192.0.2.52: ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
 ----
-
++
 In this output you can see:
 
 * The names that you give the play and each task. 
diff --git a/downstream/modules/playbooks/proc-run-ansible-network-playbook.adoc b/downstream/modules/playbooks/proc-run-ansible-network-playbook.adoc
@@ -4,7 +4,9 @@
 
 = Running a network Ansible Playbook
 
+[role="_abstract"]
 If you want to run a particular command every day, you can save it in a playbook and run it with `ansible-playbook` instead of ansible. 
+
 The playbook can store many of the parameters you provided with flags at the command line, leaving less to type at the command line. 
 You need two files for this, a playbook and an inventory file.
 
@@ -49,7 +51,7 @@ When facts are gathered from a system, either through a collection-specific fact
 
 When a module runs in a playbook, the output is held in memory for use by future tasks instead of written to the console. With most other modules you must explicitly register a variable to store and reuse the output of a module or task.
 
-For more information about facts, see [Ansible facts] in the _Ansiible Playbook Reference Guide_.
+//For more information about facts, see [Ansible facts] in the _Ansible Playbook Reference Guide_.
 
 The following debug task lets you see the results in your shell.
 
@@ -58,7 +60,7 @@ The following debug task lets you see the results in your shell.
 +
 `ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml`
 +
-The playbook contains one play with two tasks, and generates output like this.
+The playbook contains one play with two tasks, and generates output similar to the following:
 +
 ----
 $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml
diff --git a/downstream/modules/playbooks/proc-starting-automation.adoc b/downstream/modules/playbooks/proc-starting-automation.adoc
@@ -4,19 +4,20 @@
 
 = Starting automation with Ansible
 
+[role="_abstract"]
 Get started with Ansible by creating an automation project, building an inventory, and creating a `Hello World` playbook.
 
 .Prerequisites
 * The Ansible package must be installed. 
-
+* A text editor must be available to create and edit files.
 
 .Procedure
 
 * Create a project folder on your filesystem.
-
++
 ----
 mkdir ansible_quickstart
 cd ansible_quickstart
 ----
-
++
 Using a single directory structure makes it easier to add to source control, and reuse and share automation content.
diff --git a/downstream/modules/playbooks/ref-create-variables.adoc b/downstream/modules/playbooks/ref-create-variables.adoc
@@ -4,6 +4,7 @@
 
 = Create variables
 
+[role="_abstract"]
 Variables set values for managed nodes, such as the IP address, FQDN, operating system, and SSH user, so you do not need to pass them when running Ansible commands.
 
 Variables can apply to specific hosts.
diff --git a/downstream/modules/playbooks/ref-how-do-playbooks-work.adoc b/downstream/modules/playbooks/ref-how-do-playbooks-work.adoc
@@ -2,9 +2,10 @@
 
 [id="ref-how-do-playbooks-work"]
 
-= How do Ansible Playbooks work?
+= How do Ansible Playbooks work
 
-Ansible Playbooks are lists of tasks that automatically execute for your specified inventory or groups of hosts. 
+[role="_abstract"]
+Ansible Playbooks are lists of tasks that run automatically for your specified inventory or groups of hosts. 
 One or more Ansible tasks can be combined to make a play, that is, an ordered grouping of tasks mapped to specific hosts.
 
 Tasks are executed in the order in which they are written. 
@@ -32,7 +33,7 @@ A unit of code or binary that Ansible runs on managed nodes.
 
 Ansible modules are grouped in collections with a _Fully Qualified Collection Name_ (FQCN) for each module. 
 Tasks are executed by modules, each of which performs a specific task in a playbook. 
-A module contains metadata that determines when and where a task is executed, as well as which user executes it. 
+A module contains metadata that determines when and where a task is executed, and which user executes it. 
 There are thousands of Ansible modules that perform all kinds of IT tasks, such as:
 
 * Cloud management
diff --git a/downstream/modules/playbooks/ref-how-to-use-ansible-playbooks.adoc b/downstream/modules/playbooks/ref-how-to-use-ansible-playbooks.adoc
@@ -2,10 +2,13 @@
 
 [id="ref-how-to-use-ansible-playbooks"]
 
-= How do I use Ansible Playbooks?
+= How do I use Ansible Playbooks
 
-Ansible uses the YAML syntax. 
-YAML is a human-readable language that enables you to create playbooks without having to learn a complicated coding language.
+[role="_abstract"]
+Ansible Playbooks are files containing a series of instructions that define the required state of a system or application. 
+They are written in YAML, a human-readable data serialization format, and are used to automate IT tasks such as configuration management, application deployment, and orchestration.
+
+You can use YAML to create playbooks without having to learn a complicated coding language.
 //Commenting out as no downstream alternative [AAP-57435]
 //For more information on YAML, see YAML Syntax and consider installing an add-on for your text editor, see link:https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html#other-tools-and-programs[Other Tools and Programs] to help you write clean YAML syntax in your playbooks.
 
diff --git a/downstream/modules/playbooks/ref-playbook-execution.adoc b/downstream/modules/playbooks/ref-playbook-execution.adoc
@@ -4,14 +4,15 @@
 
 = Playbook execution
 
+[role="_abstract"]
 A playbook runs in order from top to bottom. 
 Within each play, tasks also run in order from top to bottom. 
-Playbooks with multiple 'plays' can orchestrate multi-machine deployments, running one play on your webservers, then another play on your database servers, then a third play on your network infrastructure, and so on. 
+Playbooks with multiple 'plays' can orchestrate multi-machine deployments, running one play on your webservers, then another play on your database servers, and so on. 
 
 At a minimum, each play defines two things:
 
 * the managed nodes to target, using a pattern
-* at least one task to execute
+* at least one task to run
 
 [NOTE]
 ====
@@ -61,7 +62,7 @@ Your playbook can include more than just a hosts line and tasks.
 
 For example, this example playbook sets a remote_user for each play. 
 This is the user account for the SSH connection. 
-You can add other Playbook Keywords at the playbook, play, or task level to influence how Ansible behaves. 
+You can add other playbook keywords at the playbook, play, or task level to influence how Ansible behaves. 
 Playbook keywords can control the connection plugin, whether to use privilege escalation, how to handle errors, and more. 
 
 To support a variety of environments, Ansible enables you to set many of these parameters as command-line flags, in your Ansible configuration, or in your inventory. 
diff --git a/downstream/modules/playbooks/ref-playbooks-yaml-ini.adoc b/downstream/modules/playbooks/ref-playbooks-yaml-ini.adoc
@@ -4,11 +4,12 @@
 
 = Inventories in INI or YAML format
 
-You can create inventories in either INI files or in YAML. 
+[role="_abstract"]
+You can create inventories by using either INI files or in YAML. 
 In most cases, such as the preceding example, INI files are straightforward and easy to read for a small number of managed nodes.
 Creating an inventory in YAML format becomes a sensible option as the number of managed nodes increases. 
 
-The following is an equivalent of the `inventory.ini` that declares unique names for managed nodes and uses the `ansible_host` field:
+The following is the same as `inventory.ini` that declares unique names for managed nodes and uses the `ansible_host` field:
 
 ----
 myhosts:
diff --git a/downstream/modules/playbooks/ref-run-network-command.adoc b/downstream/modules/playbooks/ref-run-network-command.adoc
@@ -4,6 +4,7 @@
 
 = Run a network Ansible command
 
+[role="_abstract"]
 Instead of manually connecting and running a command on the network device, you can retrieve its configuration with a single Ansible command.
 
 ----
@@ -20,11 +21,11 @@ The flags in this command set seven values:
 * the user (`-u`, the username for the SSH connection)
 * the SSH connection method (-`k`, prompt for the password)
 * the module (`-m`, the Ansible module to run, using the fully qualified collection name (FQCN))
-* an extra variable ( `-e`, in this case, setting the network OS value)
+* an extra variable ( `-e`, in this case, setting the network operating system value)
 
 [NOTE]
 ====
-If you use `ssh-agent` with ssh keys, Ansible loads them automatically. 
+If you use `ssh-agent` with SSH keys, Ansible loads them automatically. 
 You can omit the `-k` flag.
 
 If you are running Ansible in a virtual environment, you must also add the variable `ansible_python_interpreter=/path/to/venv/bin/python`.
diff --git a/downstream/modules/playbooks/ref-tips-build-inventory.adoc b/downstream/modules/playbooks/ref-tips-build-inventory.adoc
@@ -4,11 +4,15 @@
 
 = Tips for building inventories
 
+[role="_abstract"]
+When building inventories for Ansible automation, consider the following best practices to ensure efficient and effective management of your hosts.
+
 * Ensure that group names are meaningful and unique. 
 * Group names are also case sensitive.
 * Do not use spaces, hyphens, or preceding numbers (use floor_19, not 19th_floor) in group names.
 * Group hosts in your inventory logically according to their What, Where, and When:
 
 ** What: Group hosts according to the topology, for example: db, web, leaf, spine.
-** Where: Group hosts by geographic location, for example: datacenter, region, floor, building.
+** Where: Group hosts by geographic location, for example: data center, region, floor, building.
 ** When: Group hosts by stage, for example: development, test, staging, production.
+  
diff --git a/downstream/modules/playbooks/ref-use-meta-groups.adoc b/downstream/modules/playbooks/ref-use-meta-groups.adoc
@@ -4,6 +4,9 @@
 
 = Use metagroups
 
+[role="_abstract"]
+Organize your inventory by using metagroups to group multiple groups together.
+
 Create a metagroup that organizes multiple groups in your inventory with the following syntax:
 
 ----
@@ -12,7 +15,7 @@ metagroupname:
 ----
 
 The following inventory illustrates a basic structure for a data center. 
-This example inventory contains a network metagroup that includes all network devices and a datacenter metagroup that includes the network group and all webservers.
+This example inventory has a network metagroup that includes all network devices and a data center metagroup that includes the network group and all webservers.
 
 
 ----
diff --git a/downstream/titles/playbooks/playbooks-getting-started/master.adoc b/downstream/titles/playbooks/playbooks-getting-started/master.adoc
@@ -10,7 +10,7 @@ include::attributes/attributes.adoc[]
 // Book Title
 = Getting started with playbooks
 
-Thank you for your interest in {PlatformName}. {PlatformNameShort} is a commercial offering that helps teams manage complex multi-tier deployments by adding control, knowledge, and delegation to Ansible-powered environments.
+Thank you for your interest in {PlatformName}. {PlatformNameShort} is a commercial offering that helps teams manage complex multitier deployments by adding control, knowledge, and delegation to Ansible-powered environments.
 
 This guide provides an introduction to the use of Ansible Playbooks..
 

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,9 @@`
`4`	`4`
`5`	`5`	`= Running a network Ansible Playbook`
`6`	`6`
	`7`	`+[role="_abstract"]`
`7`	`8`	If you want to run a particular command every day, you can save it in a playbook and run it with `ansible-playbook` instead of ansible.
	`9`	`+`
`8`	`10`	`The playbook can store many of the parameters you provided with flags at the command line, leaving less to type at the command line.`
`9`	`11`	`You need two files for this, a playbook and an inventory file.`
`10`	`12`
`@@ -49,7 +51,7 @@ When facts are gathered from a system, either through a collection-specific fact`
`49`	`51`
`50`	`52`	`When a module runs in a playbook, the output is held in memory for use by future tasks instead of written to the console. With most other modules you must explicitly register a variable to store and reuse the output of a module or task.`
`51`	`53`
`52`		`-For more information about facts, see [Ansible facts] in the _Ansiible Playbook Reference Guide_.`
	`54`	`+//For more information about facts, see [Ansible facts] in the _Ansible Playbook Reference Guide_.`
`53`	`55`
`54`	`56`	`The following debug task lets you see the results in your shell.`
`55`	`57`
`@@ -58,7 +60,7 @@ The following debug task lets you see the results in your shell.`
`58`	`60`	`+`
`59`	`61`	`ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml`
`60`	`62`	`+`
`61`		`-The playbook contains one play with two tasks, and generates output like this.`
	`63`	`+The playbook contains one play with two tasks, and generates output similar to the following:`
`62`	`64`	`+`
`63`	`65`	`----`
`64`	`66`	`$ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml`