From 0cbe0d960547a476201b4080bc60467ae6a04425 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Sat, 11 Mar 2023 17:40:40 +0100 Subject: [PATCH] Add documentation for Terminology Tooltips (#1710) --- docs/documenting/standards.md | 42 +++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/documenting/standards.md b/docs/documenting/standards.md index b6835b2d..f5ef765f 100644 --- a/docs/documenting/standards.md +++ b/docs/documenting/standards.md @@ -62,6 +62,48 @@ inside that YAML. [YAML Style Guide](documenting/yaml-style-guide.md) +## Glossary & Terminology Tooltips + +The documentation should be written in a way that is understandable for +everyone. To help with that, we have a [glossary of terms](https://www.home-assistant.io/docs/glossary/) +that are used across Home Assistant, including our documentation. + +If you use a term that is not in the glossary, feel free to add; or improve +the definition of an existing term. + +Additionally, we have a terminology tooltip available, that can be added to +works everywhere in the documentation. This tooltip will show a definition +of the term when the user hovers over it and provides a link for more +information. This provides instant context to terminology a user might not +be familiar with. + +The syntax for adding terminology tooltips is: + +```liquid +{% term [] %} +``` + +The term referenced must, of course, be listed in our glossary, which is the +source for the tooltips. + +For example, if you write a text about automations, you could add a tooltip +like this: + +```liquid +This is an example text about {% term automations %}, which is used +to demonstrate the use of tooltips, in this case, for the term +"automations" earlier in this sentence. +``` + +The `` is optional and can be useful if you want to add a terminology +tooltip to a piece of text that differs from the term itself. In the following +example the automation term tooltip is added to the "automate everything" text: + +```liquid +Awesome, because this allowed me to {% automation "automate everything" %} +in my home! I love it! +``` + ## Renaming Pages It can happen that an integration or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add an entry to the `_redirects` file as shown below. Please consider to add details, like release number or old integration/platform name, to the page in a [note](/documenting/create-page.md/#html).