First, let me start by saying that I love HA. Have been using it for several years now, and cannot thank the developers enough for all their good work.
That being said, I wanted to point out that I have noticed a trend that the web pages explaining the Integrations are becoming more technical in nature, more geared towards programmers, and less layperson friendly. For example, when I started using HA these pages always described what the integrations could do in terms that laypersons could understand, and they almost always included specific examples showing how to install and configure the integration. These examples typically clarified any confusion that laypersons would confront. But now, instead of these detailed examples, many integrations pages just say “follow the instructions.” But to laypersons, the instructions are not always clear. For example, some instructions have a field that just says “Host.” When laypersons look at that they may wonder whether that means just the internal ip address, whether they need to use a domain name, whether they need to include the https:// or http://, etc. That is just one small example how an exemplar in the instructions would clarify.
The instructions have also become more technical. For example, the page for Z-Wave JS is not layperson friendly at all. It starts off by saying that this integration is different than the older Z-Wave integration in that it uses the “Z-wave JS driver.” I have a basic understanding of what a driver is, but no clue why I would want to use this driver as opposed to the old Z-wave integration. The page then goes on to describe the various services for the integration, with no explanation of how those services translate into actual use. E.g., the page explains how you can “set the config parameter” but I have no idea what that means. I would like to use Z-wave turn devices on and off, and to obtain sensor values. But there is nothing on that page talking about turning devices on/or or getting their sensor values. Maybe these instructions are included, but if they are they are stated in terms that laypersons will not understand.
That is just my $0.02. Hope this is taken as constructive.
I agree. And actually the trend is reflected in this forum - if you run your eye down the list of new topics most questions now are very specialised and specific, not really for the layperson.
I can see your point(s) and agree that it’s not entirely layperson friendly. That being said, I think many people who adopt an open-source solution like this probably tend to lean towards the more technical (and even nerdy) end of the spectrum (such as I do in both cases). Home Assistant was appealing to me for precisely that reason: it’s not “dumbed down” so much that it’s crippled and has tremendous technologies that you can tap directly into. I’ve been on a number of the more layperson friendly systems and they are very simple to use and easy to understand but the price you pay for that is that they are more locked down and formal.
Some people probably jump on the HA bandwagon because it’s free, but when dealing with open source stuff like HA it’s rarely geared towards laypeople and almost always geared towards the nerds like me. I employ a number of open source solutions (HA, Pi-Hole, Homebridge, etc) and all of them tend to lean very heavily towards the more technical.
All of that being said, I can say that I think most of HA has been middle-of-the-road tuned quite well. It’s a nice balance between “just click this button to do this” and being ultra technical. A good example of this is the very integrations you speak of. Until recently there was a mess of YAML to deal with to get them incorporated, but that method is moving towards a more user-friendly “just click the + button integration” instead. I would say probably 2/3 of the add-ons I use no longer rely on crazy YAML configs and are just integration additions with a few options.
So I think it’s give-and-take. There needs to be enough easy to do stuff for the laypeople, but since I suspect the larger audience is the more technically minded, it also has to cater to them as well. It’s a difficult road to walk for the core team, I’m sure.
I agree that a balanced approach is necessary. I’m not advocating simplification to the point that users can no longer customize. My point is that better explanations can be provided without dumbing down the whole project.
I was actually pleasantly surprised by the new zwavejs documentation page, I appreciated the technical details. But I agree, for someone less technically inclined it would be very difficult to follow.
The reason is that the documentation is written by the developers. And that’s never a good idea when you try to target non-technical audiences. At my job (I’m a software engineer), we have dedicated people who ‘translate’ the docs that we, the dev team write into something that normal users can understand. But in the open source world, you rarely have the luxury of dedicated documentation writers (or UX experts, for that matter). So yeah, open source projects like HA will inevitably gravitate towards the more technical crowd.
It’s no secret this software project was developed for home automation hobbyists. The prerequisites are considerably more than just the ability to install and use, say, your average phone app (which would be my definition of the technical skills of a “layperson”).
Home Assistant’s installation process alone should be sufficient foreshadowing for what lies ahead. Reading its documentation should provide a clear picture of who is the intended audience. If the installation process is a bear and the documentation is klingon, then you either make an effort to learn it or move on to use something else.
It’s a volunteer-based software project. Other than the employees of Nabu Casa, who get paid to work on Home Assistant, all other contributors work in their spare time for free and that includes the people who provide assistance on this forum. If no one is interested in writing documentation designed for comprehension by this mythical “layperson”, then it doesn’t get done. It’s as simple as that.
Nevertheless, one is free to lament about the state of affairs. It may make you feel better and maybe it will even inspire someone to contribute something. However, it’s not likely to move the ball significantly forward because this is hardly the first thread to bemoan how hard this is and why is this not like that and why isn’t it done like this … and nothing notable came out of those threads either.
Hobbyists doesn’t just include experts. Even a brief review of this forum shows that there are many users (like me) who have no technical training, but who enjoy the challenge and reward of figuring things out. The point is that the instructions used to be good enough for people without technical backgrounds who were up for a challenge, but that appears to be slowly changing.
I doubt the majority of hobbyists drawn to use Home Assistant are “experts”. How can they be “expert” in something they have not used yet?
Having used the software and read the documentation for close to 3 years now, I find the documentation to be better than ever. By that I mean it is more descriptive and thorough. As for documentation for integrations, the quality varies more than the main documentation but, again, better than 3 years ago.
UI configured integrations were introduced to make things easier, however the approach to documentation of integrations configured this way is almost nonexistent.
However i nanswer to someone above a host is a host is a host, it does not contain a protocol, or a port. A uri or url will include a protocol like http:// or https:// or ws:// and may need a port.
As someone who’s worked in IT for over 30 years, and started out life documenting installation processes for end users, I completely understand the point the OP is making.
My first job was documenting installation’s of SCO Xenix/Unix for a group of developers. They knew their processes, but unfortunately not always how to explain those to the end users, hence how my role came into being.
Since I started with HA, I’ve documented everything I’ve done (for reference, and also for when/if I need to change anything), but it’s been difficult sometimes finding the basic info to allow me to write that documentation. I also run a number of RPI’s at home, so I’m very happy around *nix based command lines, but even with that knowledge it can be a challenge to understand some of the installation and configuration processes for HA.
Also, regarding the point above about people being encouraged to update documentation, that assumes a certain level of technical expertise (and confidence) to do so. As I’ve been reading the documentation to build my own setup, I’ve noticed some minors errors (or omissions) within the documents, but am nervous about changing it without some kind of approval process or validation that what I’m changing is ok to change.
My documentation, I’m ok to change. Other peoples ? Perhaps not so much (people can be rightly quite sensitive about their stuff being edited, just look at Wikipedia ! )
Yes indeed. The fact that it runs on a Raspberry Pi is a bit of a giveaway.
To be fair, I don’t think the OP was. Merely noting an interesting trend.
One factor is that the devices currently being integrated with HA are themselves less layperson friendly. All the Hues and Alexas were done some time ago.
)