Docs: yamllint rule

src/ansiblelint/rules/yaml.md

@@ -1,33 +1,47 @@
 # yaml
 
-Our linter also includes violations reported by [yamllint](https://github.com/adrienverge/yamllint)
-but it uses a slightly different default configuration. We will still load
-custom yamllint configuration files, but the defaults come from
-ansible-lint, not from yamllint.
+This rule checks YAML syntax and is an implementation of `yamllint`.
 
-You can fully disable all yamllint violations by adding `yaml` to the `skip_list`.
+You can disable YAML syntax violations by adding `yaml` to the `skip_list`
+in your Ansible-lint configuration as follows:
 
-Specific tag identifiers that are printed at the end of the rule name,
-like `yaml[trailing-spaces]` or `yaml[indentation]` can also be skipped, allowing
-you to have more control.
+```yaml
+skip_list:
+  - yaml
+```
+
+For more fine-grained control, disable violations for specific rules using tag
+identifiers in the `yaml[yamllint_rule]` format as follows:
+
+```yaml
+skip_list:
+  - yaml[trailing-spaces]
+  - yaml[indentation]
+```
+
+If you want Ansible-lint to report YAML syntax violations as warnings, and not
+fatal errors, add tag identifiers to the `warn_list` in your configuration, for example:
+
+```yaml
+warn_list:
+  - yaml[document-start]
+```
 
-Keep in mind that `ansible-lint` does not take into consideration the warning level
-of yamllint; we treat all yamllint matches as errors. So, if you want to treat
-some of these as warnings, add them to `warn_list`.
+See the [list of yamllint rules](https://yamllint.readthedocs.io/en/stable/rules.html) for more information.
 
 ## Problematic code
 
 ```yaml
-# missing document-start
+# Missing YAML document start.
 foo: ...
-foo: ...  # <-- key-duplicates
-bar: ...       # <-- wrong comment indentation
+foo: ...  # <-- Duplicate key.
+bar: ...       # <-- Incorrect comment indentation
 ```
 
 ## Correct code
 
 ```yaml
 ---
 foo: ...
-bar: ... # comment
+bar: ... # Correct comment indentation.
 ```