Better documentation

Archive Month of "What the heck?!" (2020)
#20

I’d have to have a hard think about some ideas. The main ones I can think of straight away would be:

  • if entity state is equal to / greater than / less than X
  • if entity state is equal to / greater than / less than some other entity / entity attribute
  • if entity attribute is equal to / greater than / less than X
  • if entity attribute is equal to / greater than / less than some other entity / entity attribute
  • service- turn_on / off something if current time is before/after value / input_datetime else turn on/off

When I get a chance to log into my system I’ll try to find some more examples

#21

Documentation is the one thing where I feel confident I can improve things, and so I’ve opened multiple pull requests and they have pretty much all been accepted with little hassle. Generally when I do something and the documentation pissed me off, I go in there and fix it once I figure out what I needed to do. It’s been a great into to using git, and frenck will always double check it to make sure it’s right. Just adding concrete examples from your config can be a great help for the next guy.

Be the change you want in the world.

7 Likes
#22

Finally a place I can relate to!

As a new person to HA the documentation is seriously lacking. I was a module writer for the MagicMirror2 project and at first that was quite bad to but Thanks to some great people who wrote tutorials on how to do things with very clear examples the learning curve wasn’t quite so steep.

The learning curve for HA is pretty much like trying to climb Mount Everest. Thank God I have a friend that understands this and has been using it for over 2 years or I’d given up after a week.

Even now I am struggling to do basic things because the instructions are so lacking with info and examples that at times I just give up on it.

When a new person means examples they don’t mean a snippet of how to put it in lovelace and assume they’ll understand the rest. They don’t. There are too many posts that I can tell are from ‘newbies’ that have never gotten answered. This is why I haven’t bothered posting I just scrap what I was doing and either I delete it or if it’s something I want to work I’ll leave and ‘hope’ that in the future I’ll understand it better.

HA is truly and really awesome and is allowing me to do the things I’ve wanted to do. I have a 32" touch screen hanging on the wall that I call my control center and I’ve had it for 3 years and MagicMirror just wasn’t allowing me to do what I wanted to do but HA will. I will stick with this but at times I become really frustrated and feel helpless because I can’t find workable examples of even simple config entries.

As a teacher by education to me it’s important that examples and/or explanations help a lot. Remember some people learn by doing others by reading… I realize that a lot of you are programmers by trade and have been doing this with HA for a long time but you really need
to understand that not everyone understands what you’re saying. So please… take an extra
minute post examples [whole config examples] and if you’re really nice explain it in simple terms easy to understand.

Us ‘new’ people would surely appreciate that more then you’ll ever know.

Thanks!

3 Likes
#23

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
#24

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
#25

@petro m @Tinkerer, isn’t this basically a duplation of : -


Can they be merged ?

1 Like
#26

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
#27

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.

#28

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
#29

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
#30

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
#31

Come on, man. :roll_eyes:
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
#32

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
#33

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
How come this group config (without 'entities:' ) is correct?
#34

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. :wink:

#35

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
#36

If you are talking about the sun2 component, you are talking about a custom component. You can’t blame the HA documentation for that.

#37

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
#38

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?

#39

You don’t have to say a thing for your intent to become clear.

1 Like