Improve Discovery troubleshooting

guides/common/modules/con_prerequisites-for-using-discovery.adoc

@@ -8,3 +8,5 @@ For example, in the 10.1.0.0/16 network range, you can allocate the following IP
 
 ** 10.1.0.0 to 10.1.127.255 for leases.
 ** 10.1.128.0 to 10.1.255.254 for reservations.
+* Ensure the host or virtual machine being discovered has at least 1200 MB of memory.
+Insufficient memory can cause various random kernel panic errors because the Discovery image is extracted in memory.

guides/common/modules/ref_troubleshooting-discovery.adoc

@@ -1,35 +1,48 @@
 [id="Troubleshooting_Discovery_{context}"]
 = Troubleshooting Discovery
 
-If a machine is not listed in the {ProjectWebUI} in *Hosts* > *Discovered Hosts*, inspect the following configuration areas to help isolate the error:
+If a machine is not listed in the {ProjectWebUI} in *Hosts* > *Discovered Hosts*, it means that Discovery has failed.
+Inspect the following configuration areas to help isolate the problem:
 
-* In the {ProjectWebUI}, navigate to *Hosts* > *Templates* > *Provisioning Templates*.
-. Click *Build PXE Default* to redeploy the default PXELinux template.
-* Verify the `pxelinux.cfg/default` configuration file on the TFTP {SmartProxy}.
-* Ensure adequate network connectivity between hosts, {SmartProxyServer}, and {ProjectServer}.
-* Check the PXELinux template in use and determine the PXE discovery snippet it includes.
-Snippets are named as follows: `pxelinux_discovery`, `pxegrub_discovery`, or `pxegrub2_discovery`.
-Verify the `proxy.url` and `proxy.type` options in the PXE discovery snippet.
-* Ensure that DNS is working correctly for the discovered nodes, or use an IP address in the `proxy.url` option in the PXE discovery snippet included in the PXELinux template you are using.
-* Ensure that the DHCP server is delivering IP addresses to the booted image correctly.
-* Ensure the discovered host or virtual machine has at least 1200 MB of memory.
-Less memory can lead to various random kernel panic errors because the image is extracted in-memory.
-
-For gathering important system facts, use the `discovery-debug` command.
-It prints out system logs, network configuration, list of facts, and other information on the standard output.
-The typical use case is to redirect this output and copy it with the `scp` command for further investigation.
+.Inspecting prerequisites
+* Ensure that your {Project} and hosts meet the requirements.
+For more information, see xref:prerequisites-for-using-discovery_{context}[].
 
-The first virtual console on the discovered host is reserved for *systemd* logs.
-Particularly useful system logs are tagged as follows:
+.Inspecting problems on {Project}
+* Ensure you have set Discovery for booting and built the PXE boot configuration files.
+For more information, see xref:setting-discovery-as-the-default-PXE-boot-option_{context}[].
+* Verify that these configuration files are present on your TFTP {SmartProxy} and have `discovery` set as the default boot option:
+** `/var/lib/tftpboot/pxelinux.cfg/default`
+** `/var/lib/tftpboot/grub2/grub.cfg`
+* Verify that the values of the `proxy.url` and `proxy.type` options in the PXE Discovery snippet you are using.
+The default snippets are named `pxelinux_discovery`, `pxegrub_discovery`, or `pxegrub2_discovery`.
 
-* `discover-host` — initial facts upload
-* `foreman-discovery` — facts refresh, reboot remote commands
-* `nm-prepare` — boot script which pre-configures NetworkManager
-* `NetworkManager` — networking information
+.Inspecting problems with networking
+* Ensure adequate network connectivity between hosts, {SmartProxyServer}, and {ProjectServer}.
+* Ensure that the DHCP server provides IP addresses to the booted Discovery image correctly.
+* Ensure that DNS is working correctly for the discovered hosts or use an IP address in the `proxy.url` option in the PXE Discovery snippet included in the PXE template you are using.
 
-Use TTY2 or higher to log in to a discovered host.
-The root account and SSH access are disabled by default, but you can enable SSH and set the root password using the following kernel command-line options in the Default PXELinux template on the APPEND line:
+.Inspecting problems on the host
+* If the host boots into the Discovery image but Discovery is not successful, enable the root account and SSH access on the Discovery image.
+You can enable SSH and set the root password by using the following Discovery kernel options:
++
 [options="nowrap" subs="+quotes,verbatim"]
 ----
 fdi.ssh=1 fdi.rootpw=_My_Password_
 ----
+* Using TTY2 or higher, log in to a Discovery-booted host to review system logs.
+For example, these logs are useful for troubleshooting:
+
+** `discover-host` {endash} initial facts upload
+** `foreman-discovery` {endash} facts refresh, reboot remote commands
+** `nm-prepare` {endash} boot script which pre-configures NetworkManager
+** `NetworkManager` {endash} networking information
+* For gathering important system facts, use the `discovery-debug` command on the Discovery-booted host.
+It prints out system logs, network configuration, list of facts, and other information on the standard output.
+You can redirect this output to a file and copy it with the `scp` command for further investigation.
+
+.Additional resources
+* For more information about changing the Discovery kernel options, see the following resources:
+
+** xref:Customizing_the_Discovery_PXE_Boot_{context}[]
+** xref:customizing-the-discovery-iso_{context}[]