From b42f23d438fae301f7edac1523ff23679eadf28e Mon Sep 17 00:00:00 2001
From: Dale Higgs <dale3h@gmail.com>
Date: Sun, 1 Apr 2018 16:37:06 -0500
Subject: [PATCH] Add quote explanation and examples

---
 .../documentation/standards.markdown          | 58 +++++++++++++++++--
 1 file changed, 54 insertions(+), 4 deletions(-)

diff --git a/source/developers/documentation/standards.markdown b/source/developers/documentation/standards.markdown
index adcc3bd5214..05b1223cc61 100644
--- a/source/developers/documentation/standards.markdown
+++ b/source/developers/documentation/standards.markdown
@@ -25,25 +25,25 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo
 * Configuration variables must document the requirement status.
 * Configuration variables must document the default value, if any.
 * Configuration variables must document the accepted value types.
-  * Use `[string, int]` for configuration variables that accept multiple types.
+  * For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, int`).
 * Use YAML sequence syntax in the sample code if it is supported.
 * All examples should be formatted to be included in `configuration.yaml` unless explicitly stated.
   * Use capital letters and `_` to indicate that the value needs to be replaced. E.g., `api_key: YOUR_API_KEY` or `api_key: REPLACE_ME`.
-  * If you know that the API key or value contains [control characters](https://en.wikipedia.org/wiki/YAML#Syntax), e.g., `#`, `[`, `?`, etc., wrap it in quotes and add a note. 
+  * If you know that the API key or value contains [control characters](https://en.wikipedia.org/wiki/YAML#Syntax), e.g., `#`, `[`, `?`, etc., wrap it in quotes and add a note.
 * Component and platform names should be a link to their respective documentation pages.
 
 ## {% linkable_title Templates %}
 
 * All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the {% raw %}`{% raw %}`{% endraw %} tag.
 * Do not use `states.switch.source.state` in templates. Instead use `states()` and `is_state()`.
-* Use double quotes (`"`) for:
+* Use double quotes (`"`) for ([more information](#single-vs-double-quotation-marks)):
   * `friendly_name`
   * Single-line templates:
     * `value_template`
     * `level_template`
     * `icon_template`
     * Children of `data_template`
-* Use single quotes (`'`) for:
+* Use single quotes (`'`) for ([more information](#single-vs-double-quotation-marks):
   * Strings inside of templates:
     * States
     * Entity IDs
@@ -69,3 +69,53 @@ redirect_from: /getting-started/android/
 ```
 
 Adding a redirect also applies if you move content around in the [documentation](/docs/).
+
+## {% linkable_title Single vs. Double Quotation Marks %}
+
+Use single quotes (`'`) for strings inside of a template. It is more obvious to escape a single quote when necessary (i.e. `name` is a possessive noun), because the single quotes that wrap the string are closer in position to the apostrophe inside the string. Use double quotes (`"`) outside of a template (unless it is a multi-line template, in which case outside quotes are not required).
+
+### {% linkable_title Examples %}
+
+#### {% linkable_title Double Quotes Outside, Single Quotes Inside (Valid) %}
+
+{% raw %}
+```yaml
+automation:
+  ...
+  action:
+    - service: notify.notify
+      data_template:
+        message: "{% if trigger.to_state.name == 'Dale\'s Bedroom' %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}"
+```
+{% endraw %}
+
+#### {% linkable_title Single Quotes Outside, Double Quotes Inside (Invalid) %}
+
+{% raw %}
+```yaml
+automation:
+  ...
+  action:
+    - service: notify.notify
+      data_template:
+        message: '{% if trigger.to_state.name == "Dale's Bedroom" %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}'
+```
+{% endraw %}
+
+#### {% linkable_title Multi-Line Template (Valid) %}
+
+{% raw %}
+```yaml
+automation:
+  ...
+  action:
+    - service: notify.notify
+      data_template:
+        message: >-
+          {% if trigger.to_state.name == 'Dale\'s Bedroom' %}
+            Someone's in your base, killing your noobs!
+          {% else %}
+            It's just another door.
+          {% endif %}
+```
+{% endraw %}