And someone else who listens to the feedback. It’s a little bit sobering when you make the effort but the feedback goes nowhere and is at some point marked as “stale”.
2 Likes
I agree, it is not always nice to see feedback not being addressed, but the reality is: This is an open source project, which relies on contributions made. Things do not magically get resolved or changed, this requires someone that contributes 
So, by all means! Feel free to suggest edits (instead of providing feedback) 
4 Likes
Agreed, and documentation is usually a duller, and less sexy thing to do with one’s time. Especially if one are contributing that time for free.
Well, if I explain the same issue over and over again, I can also suggest these explanations as a addition to the documentation. 
Is there any other place to suggest additions?
@frenck maybe we could have a comment section on docs pages so we can have the best of both worlds?
- The docs remain “clean” and minimal, providing only the required info for each topic
- Users can discuss how to use each part of HA in the comments + provide detailed info.
People could use the same login as these forums.
6 Likes
In my opinion, the problem is not (just) the insufficient and inconsistent documentation.
It is the structure in the material.
For example,
entity Sun, which has been in HA since pre 0.7. No explanation how “offset” works.
the constant moving back and forth between yaml files and UI when explaining something is confounding.
Finally, lots of specialized, “Home Assistant” language used throughout the documentation without easy access to explanation.
e.g. What is a “Dashboard”?
Home Assistant dashboards are a fast, customizable and powerful way for users to manage their home using their mobiles and desktops.
That is conceptually makes sense, but where is it on my screen? How is it manifesting? What does it look like? How can I distinguish a Dashboard from a non-Dashboard? Same with card, entity, etc.
Is there a wiki out there? Maybe I will kick one off…
2 Likes
I’d have to agree that in many cases I have tried to follow the official docs to work out how to code the specifics of a particular trigger or something and the docs simply do not provide an example of all the optional settings and thus I struggle to work out how it should be done.
eg: Trying to create my first template select using the fairly new template trigger system. The example for the template select is somewhat lacking on explanation on how it all works.
4 Likes
There’s an edit button at the bottom of every single page in the documentation. The documentation is basically a wiki with a more formal review process for changes.
Thanks! That would not help.
It is not only content but a structural problem how the documentation is presented.
It is also important to put in the right amount of documentation and not explain things too much. Otherwise, more confusion and questions may arise that do not always need an explanation or answer.
One suggestion I heard was to explain config_entry format in the docs for an integration for those that do not use the UI to write automations. The UI already does the job for you. The old saying is still true today, keep it simple stupid.
What is “config_entry format”?
Thanks for your question. That just refers to config entry id. It’s confusing, right? People would never need or want to know what it is since the UI takes care of it. The current motto is streamlining experiences. Let’s keep that moving forward.
I partially disagree. In my teaching experience, lack of information is significant barrier. Adults will quickly abandon topics where all information is not readily available.
I do agree that too much in a single dump can scare some people. Not eveyone enjoys reading “manpages”. Yet, even the least technical person will end up on man pages to get the details, following a well designed introductory material.
A well structured wiki can provide introduction, basic, intermediate, and expert information without alienating either.
Just my thought.
And, to put where my words are, I am willing to financially a$$ist with this.
1 Like
I think the point here is that you know this.
Where can I look this up in the documentation?
What documentation path do I need to take to understand this?
On a positive note the link I just found Config Entries | Home Assistant Developer Docs does explain it much better than the main site, albeit a bit technical. So, I learn something! thank you 
1 Like
Thanks for chiming in. A lack of the right information is certainly not something I am trying to encourage here. A well laid out Wiki is a challenging thing to do, just not my cup of tea. I am not a UX designer or a docs master but I am under the impression that some of the best people for that job are the ones who have some tech savvy but not too much. They can view through the lens of someone who is just starting out much easier then I can.
Not so sure about that, the guy (on the dev team) who replied to him was questioning him because that phrase isnt correct, nor is it in any of the docs.
Is that something that comes up? I’ve written a lot of automations in YAML and never really needed to know that.
I do sometimes need the list of entitites for a particular automation but when I do I just do something like this:
{{ integration_entities('group') }}
And even then you can just use the name like that. I can’t think of a time I needed to know the config entry ID.
The config entry selector (in the UI) was added last release. It only applies to those integrations that use it.
Nice to see that @info4hx4 is looking at the dev docs. That’s where all the under-the-hood stuff is.
1 Like
It’s needed for the new config entry selector
https://www.home-assistant.io/docs/blueprint/selectors/#config-entry-selector
1 Like
Ah, missed that. Well fwiw it looks like it shows an example config entry ID in the documentation ludeeus linked.
That’s neat though, wonder how people will use that one.