thank you @RosemaryOrchard! How does one do that?
if-then-else in blueprints:
I copied the actions: section from my original automation and used it to replace the actions: section in the working blueprint. Then I changed the name: to “Switch Follower X”, changed switch.bulbs to !input leading_switch (two instances) and switch.desklamps to !input following_switch . “Switch Follower X” appeared in blueprints.
When I attempted to create my automation I got the error: Message malformed: not a valid value for dictionary value @ data[‘actions’][1][‘then’][0][‘target’][‘entity_id’]
In-code comments
Even if one is writing code for oneself, comments are vital to the next person using the code. The expression, “I stand on the shoulders of giants” comes to mind. Though we may not be giants, let us be those shoulders. Today, everyone here are the shoulders on which I stand. Someday, I would like to be as strong.
@petro Thank you for noting how better to present code. Is there a link to where this is documented? There may be other mark ups that I would find useful.
-OSD
There are buttons for various things on the editor toolbar of the forum too, e.g. it’s the </> button to format as code.
1 Like
@petro This topic is about documentation, though I greatly appreciate the guidance given. To that end, the documentation has a theme which I had conflated with the HA code. The theme helps the reader in understanding the documentation. When modifying the documentation, it is important to stay with the theme.
If I were to add my two-cents to the blue print page, I would put comments in the example. These would help the people that are new to blueprints:
eg:
blueprint:
name: Motion-activated Light
# name that will appear on the blueprint page. Avoid duplicate names to prevent unintended using, editing, deleting of blueprint`
description: Turn on a light when motion is detected.
# description shown when the blueprint is selected as a hint as to what the blueprint does
domain: automation
# automation, script, template see also: https://www.home-assistant.io/docs/configuration/entities_domains/
input:
# the "variables" of the blueprint
motion_entity:
name: Motion Sensor
# the varable name (Caps made lower case and underscore _ replaces the space)
selector:
entity:
filter:
device_class: motion
# device citation needed here
domain: binary_sensor
light_target:
name: Light
selector:
target:
entity:
domain: light
no_motion_wait:
name: Wait time
description: Time to leave the light on after last motion is detected.
default: 120
selector:
number:
min: 0
max: 3600
unit_of_measurement: seconds
# If motion is detected within the delay,
# we restart the script.
mode: restart
max_exceeded: silent
# automation follows, note variables are preceeded by !input
.
.
.
Thanks for your help and consideration!
OSD
The point of my post was to show you that the information you’re looking for is there, but you’re missing the fundamental understandings of YAML to understand the docs. Unfortunately, knowing YAML goes hand in hand with knowing blueprints. After all, they are an advanced portion of HA.
If there was an architecture (or task focus or UX focus) for the documentation, it would contain sections like prerequisites and where to go for more information. Understanding YAML and Jinja2 are key to becoming and intermediate or advanced user.
There should be some structure around basic, intermediate, and advanced topics and tasks. Ideally the documentation would be organized to deal with user “types”. Some users will be “appliance operators” that hope to be able to do everything from the UI.
Creating blueprints is at least an intermediate level task.
Another related thing that would help is roadmap style learning paths—These are topics you might want to read as a beginner, To become an intermediate level user these are the things you should learn.
First, Thanks for another good example of the structural problems, how is “Basic Information” part of Advanced Configuration? Advanced topics seems like a place to put anything that doesn’t fit in one of the other categories.
That YAML page is a pretty good collection of some of the YAML related issues. However, it isn’t a good tutorial, nor does it point to anything that would be. Having the first section be about YAML style guide serves developers not new end users.
The templating page is also a somewhat unorganized collection of stuff to the point that it is neither a good tutorial or a good reference manual, particularly if you haven’t been using Home Assistant for a long time.
It is an improvement that those YAML and Templating pages exist and maybe there are some efforts to add structure.
Since you respond to so many things, what would cut down on the number of responses you have to generate? What would help people ask less questions?
These aren’t meant to be tutorials, they are meant to be pages that document functionality. If you want to add a tutorial, you’re more than welcome to add one, it will likely be another page (like the blueprint one).
YAML and JINJA are both languages that are outside HA. You can look up any tutorial on yaml or jinja an it will transfer to HA. You then check out those advanced pages for the home assistant atlerations to yaml and jinja.
As a person who contributes quite a bit to this project, it seems like this thread is full of people that have ideas to change documentation but are unwilling to assist in doing so. I seem to remember having these exact conversations with you the last WTH. Here we are again, but I don’t see any contributions to any of the ideas you have (or had from the last wth). It’s like you’re expecting us to say “Yes I agree”, and then do the work you laid out.
6 Likes
Based on the posts in this topic, I would suggest:
- Improve reading skills.
- Devote time for learning new concepts.
- Don’t assume previous experience offers advantages.
- Use search and/or hyperlinks to find related content.
Lastly, to keep in mind that hundreds of thousands of productive users have preceded you and they referenced the same documentation (actually, an older, less comprehensive version).
10 Likes
I see that the response to “why no date?” is “nobody wants to fill this in all the time.” The date on page means that content is valid for the current environment, but not necessarily for any future environment.
Don’t get me wrong, documentation is hard, and tedious. As noted about “last update” It’s not done “because nobody likes to do it.”
Here’s something that would be easy to do. On the page Concepts and terminology add a section like this:
Must read reference pages
Basic Home Assistant YAML
Glossary
Index of functions, concepts, configuration, etc.
Some Recipes (a cookbook)
The author of the Index notes “Documentation is extensive, but not easy to navigate - hence this unofficial index.”
Well go ahead and add it then.
1 Like
Personally I think the documentation of HA it’s actually very good. I remember I was quite impressed about it when I first started using HA. I found most basic things to be explained well. I recall I was mostly irritated by the search function, which would often show as first results some random integrations that used the searched word, instead of the article with that word in the title. But I think that was fixed with the new interface.
What I still struggle with is templating and I wish its documentation was expanded on the basics (instead of just looking the Jinja2 docs). But then this is quite advanced feature, so you could say it’s expected it won’t be covered in step by step tutorials for newbies.
2 Likes
This “search” function deserves its own wth
There was a plan at one point to make it more broken apart for each function/filter/test etc but it’s a massive undertaking
I did provide it as feedback, in hopes that my feedback would be reviewed, found useful and incorporated. Wisely, not everyone can make the changes though one could create a fork. I choose not to fork because a fork would add confusion.
-OSD