I can see a couple of people have suggested similar things, but not that I can see that anyone has been so blunt and direct about it. This may make me unpopular, but most of the home assistant documentation sucks.
It looks like it has been written by engineers, programmers, or other people that are directly involved in the development, and I get it.
Writing documentation useful to “average users” when you are one of the developers is HARD. Things that make perfect sense to a programmer are total “Greek” to your average user. But don’t you think its time for an improvement?
I have seen countless examples of this, but at the time of writing, I can provide just one example; Critical notifications | Home Assistant Companion Docs
Right at the top, there is an “Example” But an example what exactly? If I have been linked to this page to solve an issue (and I was) this page is mostly useless to me. I have a wonderful example, but no idea what to do with it, where to place it, nothing.
Yep, there are links leading me to other places, that may or may not hold the answer as to what to do with the example. But I think we have all been there. Were we look up a tutorial, documentation or directions, and it makes “assumptions.” Like, what I need to do with that example. It is not uncommon for me at least when I look something up, be it home assistant or otherwise, where I need to look up how to do something else, in order to do the thing I am looking up… And then even at times I need to look up how to do yet something else, to do the something I need to do to do the thing I want to do (if you can even follow that.)
Home assistant has become a wonderful, powerful piece of software. But many MANY features may go unused due to the inability to get it working because of, in my opinion, poor documentation.
So, here is my suggestion. You guys have wonderful devs and programmers working on the programming. That is their skillset, and they do a great job. But maybe its time to bring someone on board who has the skillset of writing documentation.
Just my 2 cents.
Hi ShadowWizard1,
Clearly the path for everyone to start is using the GUI editor to write automations. That handles all the syntax, asks all the questions, provides possible answers, and writes things for you. If the YAML of that example automation is too advanced, then the Gui is the place the Devs have tried to make things easier as you request.
Once you have a working automation you can look at the edit as YAML button to see what was created and learn from there.
The big problem.with documentation is if you put links in to pages that explain every concept in that documentation it would be even more difficult to understand. So.
the advice as ever is to read the docs before doing things, there are plenty of docs detailing the basic concepts. The problem is people dont read them before embarking on the more complex aspects of HA.
It’s an automation… it says so “right at the top”: 
Just for clarity, I agree that the docs could use some attention… I just don’t think it’s helpful to say it “sucks”.
The documentation is mostly a technical reference. Not a “how to” guide.
It is also community supported. There are links at the bottom of every page to suggest or make improvements.
So here is a perfect example. This documentation is for someone that has written, and can understand/recognize YMAL code.
This documentation is not written for “Some guy that uses the visual editor for all his automations.” or for “Someone that hasn’t used automations before.” Or for someone like me, “Someone that has used the YAML editor so little, I can’t recognized what it does easily.”
An example. in my opinion, or how this can be improved is to add to the beginning “Here is an example automation that can be added under settings ->Automations → add new automation.” and then selecting the 3 dots at the top right, and then selecting ‘Edit in YAML’"
This is more information then I need, likely more information that those answering this thread need, but likely the exact information someone needs that has never used the YAML editor, or even knows what it is.
I agree that explaining every concept in every bit of documentation would make it hard to read. An easier way to do it may be to add the line I suggested, making the “Automations” and “YAML” hyperlinks to the documentation for them.
And I do agree, clearly the best way to start is for users to use the GUI editor. But then the example should have been shown in a way to use the GUI editor. The fact that it isn’t places this example out of reach of people that are starting out, that just want to use notifications.
I knew when I wrote this post is was likely to be quite unpopular. I have seen it many times, and heard of it many times. I likely have even done it many times. It is VERY VERY difficult for a person that understands something well to write documentation intended for use by those ignorant of the subject. And one of the biggest things that prevents documentation written for “everyone” is the fact people, developers, programmers, electricians, carpenters have a mindset of “What do you mean I can’t explain how to do this! I have been doing it for 30 years! I can do it with my eyes closed!” And the fact is, in reality, most people can’t explain it well to someone that doesn’t have their level of knowledge. Writing documentation designed for those that are ignorant of a subject is a skillset outside the skillset of the development, and it is my opinion, and suggestion to find/hire someone with that skillset then can write documentation in such a way it is helpful to all users, not just those that have a specific level of knowledge.
In a nutshell, help make all features of home assistant accessible to everyone through documentation designed for those that don’t have knowledge of the development/advanced features.
It’s possible to politely request Nabu Casa to hire a dedicated documentation specialist without disparaging the work of countless volunteers who have contributed their time and knowledge, over many years, to build the documentation. You haven’t chosen to do that.
It’s well known that the official documentation is oriented to explaining the basic operating details of a given subject. It makes assumptions about the reader’s familiarity with core concepts, occasionally directing them elsewhere for more details/background. It’s a basic reference manual, not a guidebook/tutorial.
In fairness, this is a positive, actionable aspect of your Feature Request.
Then let me take this chance to apologize. It was in no way my intention to state that the documentation has “no use whatsoever” as written. And if it is written by volunteers, then a very big thank you to them. I very much appreciate all the things the volunteers do. Home Assistant would not be anywhere close to that it is today without them, and they deserve credit and a lot of thanks.
But that doesn’t change the fact that, although the documentation is there and (I assume) accurate, I believe is only useful to specific people. And I believe a small subset of people. It is wonderful the documentation is there, that someone took the time to write it, but my suggestion is to rewrite it so it is useful to most, instead of useful to a few. The only reason I said things the way that I did is because I know from past experiences, it is VERY VERY hard for those familiar with a subject to understand what those that are not familiar with the subject need to know. From my understanding, this is one of the hardest areas of the Dunning–Kruger effect for people to recognize when it occurs to them as it becomes “You don’t know what the other person doesn’t know.” and people that know the project well look at the documentation and say “What is this ShadowWizard idiot talking about! The documentation is there, its correct. Says “Automation” right at the top. Its all accurate, no need to change it. We don’t need someone to write documentation.” and I wanted to do the best I could to have people take a moment to step back and consider the point of view I am trying to express, with all the full and correct information, if they agree with it or not.
So I guess, in summary.
I am very thankful to the volunteers, the developers, and everyone else that works on the project, you guys have done amazing and wonderful things and I appreciate all that you do, even if I can’t understand some of it.
Please take a moment, with all this information to consider the fact the documentation may be lacking, and may not be accessible to most; and if you agree with that look into changing it perhaps by bringing someone on board who has the skillset to write documentation “useable by most.” And if you disagree with me, I am okay with that too.
Either way, if I offended anyone, I am sorry it was not my intend to offend; but I believe in cases like this it is sometimes hard not to (no one likes to be told something they did, something they are working on is lacking)
Keep up the good work, and regardless if you agree with my opinions expressed in this thread I think this is an awesome project, and a project I will continue to use and continue to recommend. And thank you for taking the time to consider my suggestion.
What are you using as evidence for this claim?
FWIW, there are currently over 350 thousand registered installations of Home Assistant. Registration is optional so there’s an untold number of unregistered installations.
It would be surprising to learn the vast majority of users couldn’t comprehend the documentation.
For example, 46% use the MQTT integration which requires familiarity with its documentation in order to get it all working properly (broker, sensors, etc).
As far as I know, no one that has responded so far is paid by HA/Nabu Casa, we are all volunteers and none of us has the ability to hire anyone. Most (if not all) of us recognize that there are deficiencies in the documentation.
So, let’s stick with the example given in the original post and see if we can come up with something actionable…
The linked page has 6 automation examples. Do all 6 need “Here is an example automation that can be added under settings ->Automations → add new automation, then selecting the 3 dots at the top right, and then selecting ‘Edit in YAML’” and hyperlinks?
If not, what proportion or distribution do you think would be effective?
Keep in mind that:
- There are, conservatively, at least 2000 example automations in the docs.
- Anywhere a change is made that relies on descriptions of the UI will need to be maintained with any related change to the UI.
Are there more efficient or effective options? For example, do you think a tutorial teaching new users to transcribe automations from YAML to the UI Editor would be of use? Where in the documentation should it be placed for maximum impact?
The reason I used “I believe” is because I have no evidence. Only my limited knowledge of what is needed for proper and effective documentation that is useful to most people.
Ever read the troubleshooting manual for a refrigerator? “Problem: Refrigerator does not function. Possible cause: Refrigerator is not plugged in. Solution: Plug in refrigerator.” Documentation that you and me look at and say “OMG, seriously?” But documentation useful to the widow who had her husband do all the work, and just got a new fridge dropped off, and honestly didn’t know that it needs to be plugged into an electrical outlet, because growing up her home had an ice box, and the ice man always came when she was at school, so to her, it was a “Magic box that was always cold.” An extreme example, but an example none the less.
And MQTT understanding is needed to use it? I disagree. When I first set it up I followed a youtube tutorial, and honestly didn’t understand any of it. I downloaded an addon, copy and pasted some stuff, put the information into the other devices and things just worked. For the longest time I had no idea the devices were not connecting to home assistant itself. I have a basic understand of it now, and STILL don’t understand it all. But I got it all working, because of documentation that was “written” (youtube video) for someone that didn’t know all the ins and outs. Documentation that didn’t assume I knew what an integration was (because I didn’t, and didn’t for a long time after) and didn’t assume I knew how to install one.
Dunning-Krugar, “You don’t know what you don’t know.” but now you know that someone that didn’t understand the documentation set up MQTT. Because you just made the assumption you needed to understand the documentation to set it up.
If I am coming across as rude, or trying to “poke at you” I apologize in advance because I am not. I am just trying to show, and emphasize that each and every one of us naturally makes assumptions about everything around us without not knowing what we don’t know.
And you know what, maybe I don’t know that the vast majority of Home Assistant users have a deep understanding of the inner workings, development and programming of it, and the documentation is good for the vast majority of people, because me to, I don’t know what I don’t know.
But bottom line, and something I hope we can agree upon, if a “reasonable percentage” of people have difficulty understanding the documentation, then it would be ideal of the documentation was improved.
And to be fair, it has been given some attention recently. A new user can now start at the “beginning” and follow a fairly well signposted path through the basic concepts.
The trouble is, a very large proportion of the documentation is concerned with integrations. There are 2,896 of them, all completely different, so of course the docs have to be a technical reference. It’s hard to see how they could be otherwise.
Don’t forget unofficial efforts like the Community Guides, and in particular the Home Assistant Cookbook. You can contribute to both. There is also an A-Z index of documentation. And many integrations, including those in HACS, have excellent GitHub how-to guides.
4-year user here.
Yes, the documentation is more of a technical reference than a how-to. It all depends on who wrote the section, some excel and some suck. But that is what you get from volunteers.
Experiment. Try, fail, then post your YAML and a question in the appropriate forum. Usually “Configuration”. There’s lots of people here who will literally guide you through your issue.
I am not an expert, not by a long shot, but with the assistance of some of the people on the forums, I will claim “proficient” status. That is, the docs mostly make sense now and I can sometimes write a YAML configuration that works the first time. (OK, barely proficient).
Over the years I have been keeping a notebook - which has grown to over a hundred pages. I’ve thought of publishing it as the missing manual, but by the time I did, a significant bit of the content would be obsolete. I am amazed how well the official documentation is updated with every monthly update.
I wouldn’t compare the documentations with a refrigerator manual, I would say the the documentations is more like the technical drawings and service handbook.
I can’t in any way relate to how the example of yaml is hard to know what to do with it.
As stated previously, the word automation does say a lot.
So does “trigger”, and “action”.
I understand that these words might not say everything for someone who is brand new to HA, but if you asked a question where the answer was to set the notification level to critical then I would assume the asker has so understanding of the basics.
But maybe I misunderstood something.
For me the documentations are good enough.
I don’t generally read the text, I just skip to the code parts and/or tables. But I believe I have a better understanding of HA.
A good reference for a beginner is probably a YouTube video since they generally explain and show what to do.
But things change rapidly and you need to know that some minor things can have changed since when the video was uploaded.
I haven’t seen it mentioned, but you might want to know about the cookbook: The Home Assistant Cookbook - Index. This was created by a number of people (among others) that have responded here.
As mentioned, the docs are a technical reference. The above is a how to guide.
Neither is exhaustive though.
The YAML examples can be quite inconsistent: in some cases the main key would be there and in other cases not. This can make it hard for people 5o know where to place it. Or when an option is a list or dictionary — or either. Luckily anybody can co tribute a fix or improvement.
Understood; no supporting evidence.
No, or it would spend the first four pages telling you not to use it outside, or in a swimming pool, or for storing children and pets…
… And the next 16 pages repeating those warnings in four other languages…