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.
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
3 Likes
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.
Indeed.
but we are discussing about why docs feel insufficient. Not who can improve it.
And I gave my point supported by simple examples achievable by original devs: quality/completeness of docs is not something mandatory required from developers.
Maybe it’s issue from the past and it’s not true anymore. But in overall other posts from this WTH somehow confirm that.
3 Likes
Yes it is. What you’re pointing out is old documents from before the standards were put in place. Mqtt light is one of the oldest portions of HA.
1 Like
Yes, but not entirely true in case of mqtt light. For example warmth from template is expected by HA in mireds. Also value of color_temp variable provides value in mireds.
This info was missing for years, I’ve added that.
Good to know current standards require more detailed docs from devs