I recently found that a lot of documentation pages URL are not valid anymore, resulting with 404. It also might inpact overall feeling about dodc quality.
I created new WTH: WTH Unavailable documentation pages (404)
1 Like
You do realize that all contributions are voluntary and you just asked volunteers to spend more time posting examples and explaining them.
In the same vein, I realize you are a teacher by trade and have been collecting and disseminating information for a long time. So please … ‘take an extra minute’ to search for the examples posted in the community forum of which there are several years worth.
… and no, I am not a ‘programmer by trade’.
1 Like
I believe I understand what you’re trying to say here which is that the info is out there and can be found if you look hard enough but effectively you just told someone “google it.” What a dismissal for a sincere request.
Additionally, I don’t think that the request is too much to ask. I am a developer where I work and I get that the documentation is not as exciting as solving a problem but in the end, if I solved a problem that is difficult to follow, did I really solve anything?
Documentation is part of the solution, not a burden that we can’t expect the noble volunteer to bend down and pick up.
2 Likes
Documentation is an issue in all open source projects. In my experience people that contribute want to program stuff, not write instructions. If it bothers you, volunteer to help clean it up.
Should we just remove this forum’s search function now that it has become unfashionable to suggest people use it?
I’m reminded of a sub-Reddit called Choosing Beggars. It contains examples of people who not only want something for free, they want it with additional conditions. Like sell me your $300 fridge for free and deliver it to my apartment on the third floor. If you concede on the price but refuse delivery, they complain you aren’t doing enough and are unable to understand their needs: “I have to keep medicine refrigerated for my sick child, have you no empathy for my situation?”
If the request is for the ‘noble volunteer’ to ‘bend down and pick up’ then the ‘noble newcomer’ can at least stand up and look around. The community forum is filled with examples, supplied by ‘noble volunteers’, awaiting to be discovered, for free.
2 Likes
Yes I do realize this… I wrote modules for the MagicMirror2 project and we made it a point to do our best to realize that not everyone would just know what we were talking about so we took the time to explain it as best we could. We also were ‘voluntary’. I don’t believe it’s too much to ask anyone who has spent their time developing something to give a example of actually how to use it.
As already one developer as already said ‘it’s not too much to ask’… You may not be a programmer by trade but neither am I but it doesn’t stop me from trying to help others learn a process. AND it will help new people to better understand how to use HA and how things work. Because if I handed you 4L60E Chevy transmission and said ‘rebuild it’ without anything for you to go by… I’m pretty sure you’d be confused and lost as some of the new people are here. They want it work or they wouldn’t be here.
1 Like
Oh I’m pretty sure people DO use the search function… and even when you do and you find nothing is that the fault of the user too?
1 Like
Come on, man. 
Ok, then by this logic, let’s just do away with the documentation altogether and just use the forum.
Brother, there is a big difference between questions like what is a light entity and many, MANY statements from non-technical users who say that they don’t understand how to use what they’ve clearly read and are desperate to understand.
Honestly, if each response to “I don’t understand” on here was as plainly dismissive as your response, then I’d indeed say, yes, what value does the forum have?
However, thankfully, there are others on here that understand that simply google-it isn’t enough and try to explain things. This is wonderful and does add real value to the overall body of information about HA.
This doesn’t negate that for the non-technical, the documentation is a bear and it is unreasonable to ask a user to spend hours trying to give themselves a doctorate in CS to automate their kitchen lights.
1 Like
Exactly and the very point of this post. Thank you for understanding that people do indeed want to learn and aren’t afraid to try but at times it can be more then they can understand at that moment.
Now if someone where here [and TRUST ME I know this from MM2 forum] where people are here with the intent of not learning but are asking you to just do it for them that is a whole different animal. Because they aren’t learning and you will be doing it for them for a long time. THEN I agree with him. However, in my case, I am here trying to ‘get this’… and it’s not because I haven’t tried for a few days and googled and used the search only to find dead ends…
The Original MM took me 3 days to get working… I would run it, get errors go to Google and fix them then I would try again… and I kept trying until I got it working and now I write modules for it. I WILL get here with this too but at times and after many many attempts and research still need help. So far it’s been very positive results. I do Thank ALL the people that take a minute or two of their time to help and I’m hoping that in the future I can do the same for someone else!
1 Like
Developers are already required to create/update documentation related to their PRs. The amount of detail provided is at the developer’s discretion. As far as I know there’s no ‘minimum number of examples’ rule so that explains why some integrations have none, one, or several examples.
If you would like to see that changed, lobby the development team to enhance the criteria for minimum documentation requirements. Otherwise, the inclusion of examples, for an integration, will largely depend on interest. For example, I was interested in the UPB integration so with the aid of the integration’s developer, I submitted several examples.
1 Like
Yes and they are VERY helpful… even one good example. I think what I mean here is for instance… say you want to extend the sun portion. Someone has created it and making it work is more then a 1 step process.
I had to create a yaml file to put in my ‘sensors’ dir… Then I had to take the actual js file and put that in custom_components dir under Sun2…
There really isn’t any explanation anywhere explaining that… it was because I understood it for the most part because I had to do it for another thing I had recently done. Had I not known that and it wasn’t explained I would have never gotten it to work. That’s my point… that kind of thing needs to be explained even if it’s a bare bones explanation and trust me I’m trying to get 2 other things working right now and there’s no explanation or understandable explanation as to how to get it working so for a few days it’s been trial and error. No big deal, BUT I know me and having tried so many different things that for me to get it working at this moment is going to be purely by accident. 
Yet you feel it’s reasonable to demand others spend hours trying to compose docs for users who bristle at the suggestion to use the search function.
Check my profile. Clearly I spend a lot of time helping the “I don’t understand” questions. So do many others and that’s the value of the community forum.
Having spent a lot of time with Home Assistant, I believe if one is ‘non-technical’, they have chosen the wrong software. It will eventually cater to that demographic but it’s not there yet (and the state of the documentation isn’t the principal hurdle). Currently, this is software for hobbyists and tinkerers.
1 Like
If you are talking about the sun2 component, you are talking about a custom component. You can’t blame the HA documentation for that.
Yep, there is no way in hell I’d hand this software off to a non-technical user.
I’ve been using HA myself for about 3 years hoping that the project would mature it’s documentation along with the functionality but alas, no. It also doesn’t appear that it will.
You seem to think that an open source project can’t expect this. Honestly, nothing puzzles me more than your statements here. I may be showing my age here a bit but I remember a time when developers of open projects valued accessibility so much that they would go out of their way to make the documentation usable by others who didn’t know how to do what they did.
Maybe I’m glossing over my experiences but I look at this project and specifically the attitude toward newbs and I have to say that I don’t ever expect this project to achieve the usability goals that I’ve heard the founders express.
… and yes, I believe it is absolutely reasonable to demand better documentation. You all lament having to spend hours fielding questions. Imagine how much of this support time might be mitigated if the documentation was more complete.
Then, I’d be more inclined to support your easy dismissal of this very earnest request from someone who’s tag line is “Thank you for all those who help out!”
1 Like
I don’t know what led you to that observation but I said no such thing.
I have a question for you. You said you have been using Home Assistant for 3 years. According to your forum profile, you joined 10 days ago. Is that correct?
You don’t have to say a thing for your intent to become clear.
1 Like
No one is blaming HA… it was an example.
Thank you for all the replies. Lets just end this one 
Thank you all again for all you do!
1 Like
How can any custom component be an example of (the core) HA ?
Custom component documentation is written (or not) at the whim of the author, you can’t hold HA devs (etc.) responsible / accountable