I’m fairly new to Home Assistant. I’m still learning the ropes. Unfortunately I have found the documentation to be somewhat lacking.
The single most frustrating thing I have found about the documentation is that the examples have no context. The sample code is trimmed to the bare minimum number of lines to show the syntax for the feature being described, and the lines of code that would show you how that feature is used are missing.
For example, last night I was trying to figure out how to use the mqtt publish service as the action of an automation. Here’s the sample from the documentation…
Right, and it would have been awesome if that had been on the documentation page for the mqtt component.
I went through all of the automation documentation and all of the mqtt component documentation and there was nothing in there that would show me how to construct that yaml entry.
Well, the documentation on automation and services shows the layout, and at that point you would just substitute the service for mqtt.publish
The documentation would be HUGE if they had to repeat every aspect over and over. If you start at the beginning and look at it as learning the concept of Home Assistant… once you understand the tigger, condition and action layout, you can substitute it with whatever platform, condition or service you need by looking at the service code, such as you did with mqtt.publish, to find out that it requires topic and payload, with an optional retain and qos, then you just plug those into the same format you learned from the trigger, condition, action documentation
A lot of people just jump around the documentation to the part they want, like mqtt, but if you are new to Home Assistant, YAML and Jinja2 templating, you should read through all of the Getting Started materials to get a better understanding of the whole concept before going directly to one specific service.
All you really need to learn thoroughly is the layout of trigger, condition, action and then you can pull the pieces you need from the JSON examples, as everything uses YAML layout.
I agree absolutely. I don’t expect everything to be documented everywhere. But on the other hand, if every aspect is documented in exactly one place and you don’t find that one place then you are screwed. There needs to be a bit of overlap.
And I did at first jump straight to the stuff I was interested in, and then when I didn’t find what I was looking for I read through all of the automation documentation and all of the MQTT documentation. And then I went through all of the Automation examples and then started going through the example configuration.yaml files. I still couldn’t figure it out.
And BTW, I’m a professional software developer. I do know how to use technical documentation.
Given that, you probably have experience with GitHub, right? The doc pages are available for editing in GitHub so maybe you can contribute some corrections or clarifications.
The solution of your described problem is at least documented at three places. Of course, there is always room for improvement, thus feel free to create PRs against the documentation.
Once I know enough to do that, I’ll suffer from the same problem as you guys which is the problem all tech writers have. Once you have the knowledge it’s hard to appreciate the perspective of the person who doesn’t have it.
That’s actually not my problem; my problem is getting to understand GitHub and markup better. Until then I troll the boards looking for questions I can answer and learning from other threads.
I found this thread when searching for exactly the same thing since the docs didn’t help me enough.
I have a TODO list of docs I want to add to (I’ve already done some). I’ll add this to my list.
I do agree that adding context (making examples more complete, not necessarily exhaustive) would be a huge help without a huge extra amount of docs.
