@frenck maybe we could have a comment section on docs pages so we can have the best of both worlds?
People could use the same login as these forums.
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…
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.
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.
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 
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.
It’s needed for the new config entry selector
https://www.home-assistant.io/docs/blueprint/selectors/#config-entry-selector
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.
It’s already in use in Google Sheets. Just in time, too. Would look silly on how to select one from multiple config entries.
let me share my few cents.
To me the docs mostly feel like written because devs are forced to provide them in order to pass review. Not because they are confident the docs are useful.
In result docs contain too general information lacking useful details. The details needed to understand how something work (ie relationships between various terms) or how to use it in detail.
For example when setting mqtt light it would be useful to know what values are valid. For rgb you can guess it’s 0-255. but what about brightness? 0-255 (range of 2 bytes in decimal system), 0-100 (%) or 0.0-1.0 (% decimal representation)
And what about warmth? Kelvin or mireds?
Snd what values are provided by variables available to be used in templates.
try to figure out how to work with HS color model in default or template schema. Using search on docs page you find an example in json schema. but does user can be dure it can be applied to other schemas?
At some point I extended docs of mqtt light template schema with some missing details but… why a user is ever forced to guess values?
imo it’s work of original developers to create as complete reference docs as posdible (they know exactly valid value ranges). it’s not something exceptional. Those are basic information which should be a part of every reference docs.
And tbh such an incomplete docs shouldn’t pass review.
Right now this page deserves serious overhaul. I’m sure it could have been avoided
Have at it, didn’t you just reconfigured your lights? You should have some good incites for the page.
As a sidebar, kelvin, mired, and warmth are hardware dependent and don’t have static ranges.