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.
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.
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
Yes, the downside to the requirement is that old integrations still lack proper info and examples
I do not want to lose sight that this is volunteer work. By no means am I badgering for developers to write the documentation. I also rather have them concentrate on developing, their core competency, instead of writing, which what I gather do not favor.
I am confident with appropriate Instructional Systems Design (ISD) we can get the material started. Thereafter much of the drudgery would be distributed for users, while the ISDs oversee the contents & structure.
Related minor WTH - WTH Do documentation pages not show last updated date?
If there was an easily visible last updated date at least it would be easier to spot documentation that hasn’t been maintained in a while.
I’m just going to throw this out there… I’ve been using HA since 2017… I have only ever used the official docs and the community forums… (unless it was a Linux OS type issue) (or the GitHub for a specific custom component) I don’t use YouTube or blogs because HA was and is changing too quickly. Especially at that time… if you stick with the real docs you will have much better luck as far as accuracy than using JimmytheTechGuys Blog. But as mentioned if you see an error we all have the ability to correct it…
I’m not trying to argue, just wanted to mention that the official docs have served me very well over these years… so I’d have to kindly disagree with you.
Sorry, I’m not trying to call you out, but you’ve brought up what I think is one of the larger underlying issues with the documentation:
If you’ve been using HA for a year or more, your documentation needs and view of the documentation is vastly different that a new user today that doesn’t yet understand much about Home Assistant.
When you already have an in-depth understanding of the system through experience, your documentation needs are for reference material.
However, a new user needs overview information, tutorials, and navigation that will help them understand all the moving parts and put them in context.
Someone who wants to improve the documentation needs to put themselves in the shoes of a new user and think about what does someone who doesn’t have HA expertise need to understand.
For example, imagine you just got Home Assistant installed and want to learn how to configure it, go to the top documentation page - https://www.home-assistant.io/docs/ You see this:
Click Configuration. This brings you to https://www.home-assistant.io/docs/configuration/
There is exactly one sentence that mentions the settings page, then we are off into the deep end about configuration.yaml that is going to be way over the head of a new user.
If you’ve been a round a long time, this may seem fine. But if you take a moment to think about that this may be one of the first documentation pages a new user visits after installation, and then think about what information should be there, this is the wrong content for this page.
A few of the things I would expect to be on https://www.home-assistant.io/docs/configuration/:
Maybe some of this exists in other places, but not under configuration where one is likely to look
As you mentioned, creators have been trying to fill that gap with videos and blogs. But as you mention they frequently go stale. Home Assistant has a rapid pace of innovation and evolution, so this is somewhat to be expected. Videos and tend to be write once, rarely updated, except through comments, and tend to clog up search results.
I mean I would expect the user to start with Installation:
I guess Configuration is kind of out of place in the previous screen, since it feels like these should be top level rather then buried under installation. But like most of what you just mentioned is in here. Takes you from true installation through onboarding and discovery to automation around your new stuff to a relevant example and then leads you to the community and more advanced topics if you want.
Merge this into the previous page and merge “Configuration” with “Advanced Configuration” and its pretty close, no?
So the Getting Started page you pointed out somewhat jumps from auto discovered integrations to automation. It does mention that you can add other integrations, though never really defines what an integration is or explains that you might need to add integrations such as Zigbee/Zwave/MQTT that gives you access to other networks/device domains which in turn might auto discover other devices or let you manually add them.
There is no configuration page. I wouldn’t really expect to find configuration info under onboarding.
Advanced configuration goes into configuration.yaml. It’s good to have that, though the example needs to be rethought, it shows editing through YAML the settings that are maintained in Settings->System->General. It should at least mention that these are normally maintained through the UI and this is just an example of overriding these the YAML way.
The Getting Started set of pages do have somewhat up to date content in tutorial form that matches the current experience of installing HA, HAOS, etc. However these pages are fairly brief and have a bunch of gaps. They are missing a lot of where to go for more information.
The pages under Documentation generally have older content and may be somewhat different from the current HA + HAOS experience. For example, look at the troubleshooting page https://www.home-assistant.io/docs/troubleshooting/. That page starts with talking about pip.
The point of all of this, is if you want to meaningfully improve the documentation some thought needs to be given to what a user needs to know and the perspective of relatively new users. The Getting Started pages are definitely a step in the right direction, but the documentation pages need work.
I am late to this conversation, but please lets not have a wiki. They too quickly get out of date.
I’ve been using Home Assistant for some time, and I almost never find usefull information in the docs, the examples doesn’t cover the subject or doesn’t exist, the language might be understandable for a true programmer, and being an algorithmic guy who’s actual programming is 30 years ago, it doesn’t make sense the way it’s written, the search engine is horrible, and the results give no meaning, the overview to the right is very bad, and helps only if you know where to look.
So spiffing up and reorganizing the docs is absolutely needed, and it’s a Herculean task. What I really don’t understand is the intense pushback from Nabu Casa people, it’s like they don’t WANT to see the need for this, I know it’s not sexy as making a new integration, and programmers are the worst people to document stuff, because terms are ‘inherently’ known, and thus not added for everybody else.
Who said that?
You’re getting pushback because all the people who contribute to the documentation understand it. It 100% makes sense to me. I know I’m not the best person to write or change the documentation because I don’t see ways to improve it. It’s likely that the whole Nabu Casa team thinks the same way.
So, why doesn’t someone here step up to the plate? I’m sure no one is going to shoot down the idea of making the documentation better for beginners.
it is a general known fact that:
As a developer by trade I feel I have to word something here:
It’s incredibly hard to document your own code in a way that is 100 % understandable for someone with very little knowledge of the implementation. That is because you yourself have the best and entire knowledge of how the code you just wrote works.
This is the same reason it’s incredibly hard to test your own code - you know how it’s supposed to work and it’s pretty hard to come up with all the ways someone can fuck it up when you know the “happy flow” like the back of your hand.
That is why it’s very important that someone else than the developer tests the implementation and also why the persons most suitable to help improve the documentation when something is lacking is often the persons that didn’t understand the docs in the first place but then found a solution.
That said it doesn’t mean that every suggested change to the docs are good and should be implemented.
Plus one to that .
which is the case for all documentation sites or forums I know.
IMO the most efficient way to search sites is google search limited to particular address
It’s incredibly hard for anyone else to document your code when “you yourself have the best and entire knowledge of how the code you just wrote works”.
No one else knows what options, capabilities are in your code, how to enable / them etc.
I think it has to be a joint effort.
We already have the developers contributions right now. So…
I have made a few changes to the docs, it isn’t that hard, but you have to learn some markup. Pretty easy to learn.
