diff --git a/docs/voice/intent-recognition/style-guide.md b/docs/voice/intent-recognition/style-guide.md new file mode 100644 index 00000000..925a6eae --- /dev/null +++ b/docs/voice/intent-recognition/style-guide.md @@ -0,0 +1,42 @@ +--- +title: Response Style Guide +--- + +This document describes the style guide for responses. + +## Be concise + +Responses should be concise and to the point. They should not contain unnecessary information. + +- If a command is targeting a single device, don't repeat the name of the entity in the response. +- If a command is targeting an area, don't repeat the name of the area or it's entities in the response. +- If a command is asking for a list of entities, list all if 4 or less. Otherwise list first 3 and say "+ 2 more". + +Readability is important, so use below code to generate "+ 2 more" style sentence when needed. Do not create your +own variant. + +```jinja2 +{% if query.matched %} + {% set match = query.matched | map(attribute="name") | sort | list %} + {% if match | length > 4 %} + Yes, {{ match[:3] | join(", ") }} and {{ (match | length - 3) }} more + {%- else -%} + Yes, + {% for name in match -%} + {% if not loop.first and not loop.last %}, {% elif loop.last and not loop.first %} and {% endif -%} + {{ name }} + {%- endfor -%} + {% endif %} +{% else %} + No +{% endif %} +``` + +## Use the correct tense + +Responses should be in the present tense. For example, "The light is on" instead of "The light was on". + +## Use the correct voice + +Responses should be in the active voice. For example, "The light is on" instead of "The light is being turned on". + diff --git a/sidebars.js b/sidebars.js index 033b47d4..d220583e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -114,7 +114,11 @@ module.exports = { { type: "category", label: "Bluetooth", - items: ["bluetooth", "core/bluetooth/bluetooth_fetching_data", "core/bluetooth/api"], + items: [ + "bluetooth", + "core/bluetooth/bluetooth_fetching_data", + "core/bluetooth/api", + ], }, ], }, @@ -240,6 +244,7 @@ module.exports = { "voice/intent-recognition/test-syntax", "voice/intent-recognition/supported-languages", "voice/intent-recognition/contributing", + "voice/intent-recognition/style-guide", ], },