doc: Reword user data debug section (#2019)

1 files changed, 21 insertions, 6 deletions

diff --git a/doc/rtd/reference/faq.rst b/doc/rtd/reference/faq.rst
index 46d37bb1..87aade59 100644
--- a/doc/rtd/reference/faq.rst
+++ b/doc/rtd/reference/faq.rst
@@ -140,22 +140,37 @@ re-run ``cloud-init``:
 How can I debug my user data?
 =============================
 
-Two of the most common issues with user data, that also happens to be
-cloud-config is:
+Two of the most common issues with cloud config user data are:
 
 1. Incorrectly formatted YAML
 2. First line does not contain ``#cloud-config``
 
-To verify your YAML, we do have a short script called `validate-yaml.py`_
-that can validate your user data offline.
+Static user data validation
+---------------------------
 
-Another option is to run the following on an instance to debug user data
-provided to the system:
+To verify your cloud config is valid YAML you may use `validate-yaml.py`_.
+
+To ensure that the keys and values in your user data are correct, you may run:
 
 .. code-block:: shell-session
 
     $ cloud-init schema --system --annotate
 
+or to test YAML in a file:
+
+.. code-block:: shell-session
+
+    $ cloud-init schema -c test.yml --annotate
+
+Log analysis
+------------
+
+If you can log into your system, the best way to debug your system is to
+check the contents of the log files :file:`/var/log/cloud-init.log` and
+:file:`/var/log/cloud-init-output.log` for warnings, errors, and
+tracebacks. Tracebacks are always reportable bugs.
+
+
 Why did ``cloud-init`` never complete?
 ======================================