Apply copy edit

Author: nathan-contino

documentation/asciidoc/accessories/audio/configuration.adoc

@@ -37,7 +37,11 @@ All the necessary mounting hardware including spacers, screws and connectors is
 
 === Hardware versions
 
-There are multiple versions of the audio cards, and the version that you possess determines the actions required to configure it. Older IQaudIO-marked boards (black PCB) are electrically equivalent to the Raspberry Pi-branded boards (green PCB) but have different EEPROM contents. After attaching the HAT and applying power, if your audio card has an LED to indicate power make sure it is illuminated (for example, the PWR LED on the Codec Zero must be on). After establishing the card has power, the following command can be used to confirm which version you have:
+There are multiple versions of the audio cards. Your specific version determines the actions required for configuration. Older, IQaudIO-branded boards have a black PCB. Newer Raspberry Pi-branded boards have a green PCB. These boards are electrically equivalent, but have different EEPROM contents.
+
+After attaching the HAT and applying power, check that the power LED on your audio card is illuminated, if it has one. For example, the Codec Zero has an LED marked `PWR`.
+
+After establishing the card has power, use the following command to check the version of your board:
 
 [source,console]
 ----
@@ -98,7 +102,20 @@ The following command will set your device to use the on-board MEMS microphone a
 $ sudo alsactl restore -f /home/<username>/Pi-Codec/Codec_Zero_OnboardMIC_record_and_SPK_playback.state
 ----
 
-It's possible that this command may result in erroneous messages such as "failed to import hw" or "No state is present for card". In most cases, these are just harmless warnings. Other errors such as "Remote I/O error" need to be given more attention because they are usually indicative of a hardware problem. In Linux I2C, a "Remote I/O error" (```REMOTEIO```) means the kernel can't communicate with an I2C device.
+This command may result in erroneous messages, including the following:
+
+* "failed to import hw"
+* "No state is present for card"
+
+In most cases, these warnings are harmless; you can safely ignore them.
+
+However, the following warnings may indicate a hardware failure:
+
+* "Remote I/O error"
+
+In Linux, the following warnings indicate that the kernel can't communicate with an I2C device:
+
+* "Remote I/O error" (`REMOTEIO`)
 
 In order for your project to operate with your required settings when it is powered on, edit the `/etc/rc.local` file. The contents of this file are run at the end of every boot process, so it is ideal for this purpose. Edit the file:
 
@@ -154,7 +171,15 @@ pcm.!default {
 
 Press `Ctrl+X`, then the `Y` key, then *Enter* to save. Reboot once more to complete the configuration:
 
-The desktop environment in modern Linux distributions such as Raspberry Pi OS will typically use PulseAudio or PipeWire for audio control. These frameworks are capable of mixing and switching audio from multiple sources and they provide a high level API for audio applications to use. Out of the box, a lot of audio apps use these frameworks by default which removes the need for them to interact directly with ALSA. Creating ```~/.asoundrc``` is only recommended if audio applications are communicating directly with ALSA or running in an environment where PulseAudio or PipeWire are not present. Usage of this file is not recommended if running the Raspberry Pi OS desktop environment because it can interfere with the UI's view of the underlying audio resources. The UI may take action to automatically clean up and remove this file if it exists so careful use of it is recommended, especially if it's intended to set any ALSA defaults.
+Modern Linux distributions such as Raspberry Pi OS typically use PulseAudio or PipeWire for audio control. These frameworks are capable of mixing and switching audio from multiple sources. They provide a high-level API for audio applications to use. Many audio apps use these frameworks by default.
+
+Only create `~/.asoundrc` if an audio application needs to:
+
+* communicate directly with ALSA
+* run in an environment where PulseAudio or PipeWire are not present
+
+This file can interfere with the UI's view of underlying audio resources. As a result, we do not recommend creating `~/.asoundrc` when running the Raspberry Pi OS desktop.
+The UI may automatically clean up and remove this file if it exists.
 
 [source,console]
 ----