User-created documentation embedded within HA

Feature Requests
21

I don’t want to be rude, but you are awfully harsh on the OP. You didn’t explain that what you did was done in the UI and the previous post only mentioned yaml.

Also there’s really no need to be condenscending to a new user of HA about what they consider hard to use or intuitive. On the contrary, I think HA authors should listen to such voices more, because it’s so hard to get perspective of a new user when you’ve been doing this for so many years.

Personally I do agree that the way you access the description editing pop-up is unituitive. Considering multiple people in this thread were not aware of the UI option, including experienced users, clearly it is not that obvious.

I would rather put it directly in the UI, some button next to the description field area, “add description” or “edit description”, depending on whether something was added already or not.

But also, there are tons of other UI-related topics that should be prioritized over this. I’m glad they started working on it.

1 Like
22

Why do you feel it was necessary when the request explicitly asked for a means to enter documentation via the UI?

It was the OP who erroneously jumped to the conclusion that it was not entered via the UI … and kept countering with “I don’t know YAML” even after being told it wasn’t needed and the example wasn’t created with it.

The inability to find/edit the Description field isn’t a historically common problem reported in this forum. That’s a fact, not condescension, and was presented as a rebuttal to the OP’s assertion that it wouldn’t occur to “many folks” where to look for it.

Can you elaborate on what you mean by “not aware of the UI option”?

Some of the eight people who contributed to this topic indicated that they felt the word “Rename” was unintuitive. That’s a valid statement of opinion, not a lack of awareness.

FWIW, “Rename” wouldn’t be my first choice either but I appreciate the challenge of choosing a brief command that conveys its intended purpose and can be translated into multiple languages (with equivalent brevity).

If you feel strongly about the command itself being unclear or its location is obscure or whatever else seems unintuitive, then I suggest you create an FR that proposes a better alternative.

1 Like
23

I’ve marked this post as Solved but I feel that I need to respond to you.

I’m not a developer or in any way an expert in HA, I’m simply an enthusiastic end-user who posted a benign suggestion and didn’t expect it to be met with hostility or to be condescended to. I’m sure you have expertise in HA and I respect that but I’d suggest that you are being unnecessarily combative. There may be thousands of posts on this forum and there may be few queries like mine but is seems to me that they are nearly all by developers or people with expert knowledge. It also appears from this thread that some of them weren’t aware that the description could be edited via the ‘Rename’ menu option.

When I said ‘most folk’ I meant casual users, the end-users, who wouldn’t imagine that the place to edit the description would be via the ‘Rename’ menu option. There is a world of HA users beyond this forum. I realise that I talked about the ‘UI’ when I meant the ‘Visual Editor’ but I’m essentially a HA noob who doesn’t want to look beyond the Visual Editor. I probably do leave the description fields blank when I create the automations but how would I know that I should go to the ‘Rename’ option to update the description? Thank you for explaining what a ‘kebab’ menu is but if you read my request you’d know that I understand that perfectly.

This was my first post on this forum and, thanks to you, likely my last.

24

In my case, a glance at the available choices in the menu led me to conclude the only one that fit the task was “Rename”. I clicked it and it proved to be the right choice.

Full disclosure: I learned it two days ago while composing my first post in this topic. I don’t use the Description field at all so editing it via the UI was something new for me. I document my automations another way.

Sorry to hear that. Good luck.

25

Intuitive?? Maybe HA should advise users to click every option until they find the right one instead of it being immediately obvious? Are you serious or just being deliberately obtuse? It’s not about you, it’s about the thousands of casual users who would never even look at this forum but would benefit from a menu option that specifically mentions ‘Description’ rather than ‘Rename’ of the automation/script. That’s what my FR was and I’ve no idea why you’re fighting me on this.

26

Thanks, though I feel that It’s probably most ingenious.

27

You had asked how would one know to choose “Rename” and I shared my first-hand experience with you.

I honestly never had a need to use that command because, for a variety of reasons, I don’t use the Automation Editor (other than when necessary to help others); I regularly use Visual Studio Code to compose my automations. So it was genuinely the first time I had use it for that purpose.

If you review the Automation Editor’s list of menu items, they’re verbs, not nouns so ‘Description’ alone probably wouldn’t be acceptable. In addition, they consider Description to be associated with Name, hence the single “Rename” command instead of two separate “Edit Name” and “Edit Description” commands.

Perhaps the Description field’s contents, when displayed at the top of the page, should have an edit button (pencil icon) next to it. Look at the screenshot I posted above and imagine a pencil icon next to the text I created.

It would need an edit button because two modes are required, one for editing markdown-formatted text and another for displaying the markdown-formatted text (effectively the same paradigm as for editing and displaying forum posts).

The “Rename” command would be retained but only for changing the automation’s Name, not its Description.

If you meant I was being disingenuous, I wasn’t. I honestly wish you the best of luck with your home automation projects.

28

I would still love to have one place in the UI with at least one row per automation, at least two columns would be the name and description, that would allow you to see the name and edit/update the description for all of them in one place. :slight_smile:

Currently you have to look at each one individually to see or edit it’s description.

29

I’m sorry for that. Written text can come over sometimes with another intonation then meant.

1 Like
30

I’m afraid in this case the intention was understood very well. There was no misunderstanding. It’s always a pity when toxic people are given allowance to create such atmosphere because they contribute a lot of their time to the community. It happens everywhere though, and to be fair this forum is better than the average.

1 Like
31

Or having people completely unrelated to the conversation and just throw in toxic comments to make some kind of point to a first responder to the OP’s question.

Even though I was also a first responder to the OP and I realize this is also a toxic comment, but I had to point out that your input here did little to help the situation if anything.

And, believe it or not, nearly all the responses to questions here in the forum are from volunteers, and we have no way to affect this:

No one was attacking anyone until…

If you would like to volunteer to help people, please do. I spend about 50hrs a week doing it. We could always use constructive help.

2 Likes
32

First of all, I was already taking part in the conversation.

Secondly, I just can’t stand behaviour that was presented here, that’s why I decided to react. Believe it or not, I was trying to be delicate and my first comment about the other person was way friendlier than my initial reaction. I was hoping they could take a minute to think about what they are doing.

Later, after their further comment I realised I’m wasting my time and that they didn’t just made a mistake, but that’s who they are and how they act normally. So I didn’t reply, not too fuel the pointless discussion. Until OP came back and was gaslighted, I again felt I should support them. End of story, I’m not going to participate in this discussion further.

That’s great for you. I hope it brings you a lot of joy, I’m serious. 50 hours a week is more than a full time job, it’s a really huge part of your life. It’s probably most if not all of your free time. You must have helped thousands of people and I’m sure they all appreciate it.

But please, if it ever gets to the point where it starts feeling like a job, where you feel you have to do it even though you don’t really want to, take a step back, get a break or maybe quit completely.

For the context, I’ve been part of various community places, volunteered a lot of my time and managed volunteers a lot, both as volunteer and in my professional work. It’s not easy. People volunteering a lot of their time can get frustrated and burned out, in my experience this is even bigger risk than in a paid job. I know very well it can be very addictive, intoxicating, that feeling you get when you managed to answer someone’s difficult question. It’s making it so hard to get some distance.

Anyway, it was really not my original intention to write this much here. I recognize the symptoms in my own behaviour, I was spending to much time in the last days here. So I will listen to my own advice and will get a break. I do really wish this community all the best and if anyone feels offended by what I wrote above, I apologize.

2 Likes
33

If you spend some time looking for other responses by Taras/123, you will note:

  1. He puts a lot of thought into his answers.
  2. His answers are with almost no exception highly accurate and comprehensive.
  3. He is excellent at generalising solutions.
  4. He can distinguish his personal preferences from someone else’s intent and understand the background of something (remember: hindsight is perfect).
  5. He uses impeccable language.

The last point perhaps throws some people and while it can come across as direct, I haven’t perceived him as rude. It’s best to try to not read emotion into written text. While I say that, it’s sometimes hard for me too. An attitude of positive intent is probably best around here.

1 Like