I currently maintain documentation about my Home Assistant setup that includes simplified English descriptions of my automations and scripts etc. that I often refer to but sometimes don’t update. I would suggest that these could be embedded somehow so that I could refer to/edit them from within the HA UI.
I’m a Home Assistant enthusiast but often neglect to update documentation as it is kept separately (I tinker and then don’t update) and I feel that if I could access documentation from within the UI then I’d be more likely to update it. I’d suggest that perhaps there could be an option within an automation/script kebab menu to view user-created documentation.
There is a place for descriptions of automations ofd course, however I agree itg would be great to have some kind of a UI which would allow us to view and/or update them all on one screen
Click the ‘edit in YAML’ button and add text in the description firld, or fill in the Description field when you first save the automation…
It then show up like 123 mentions above…
If one of the suggestions listed solves your problem, please consider clicking the solution button to close the thread.
Thanks, your reply is helpful and I honestly wasn’t aware of the ‘description’ field within YAML but then I don’t know much YAML and so work from the UI the majority of the time. I only edit in YAML when I can’t do something from within the UI (e.g. continue_on_error/templates).
I’m a HA enthusiast but only a casual home enthusiast and don’t really want to edit in YAML/learn markup codes just to create documentation and I’m really looking for a way that it could be incorporated within the UI tbh.
Not a huge big deal to me, only a suggestion. I appreciate your reply though.
I didn’t know about the ‘description’ field within YAML but this is not really what I’m looking for tbh. I’m really looking for a way that I could create/maintain formatted documentation from within the UI without having to edit in YAML (I avoid YAML as I don’t know it much).
Did you even look at that?
You are not ‘really’ editing yaml there.
The UI already gives you the description field with empty quotes it you didn’t add a description in the UI when you first saved the automation/script.
Just put whatever you want in there inside the quotes. and if you need quotes inside the description, use single quotes.
Chances of getting an integration or some modification in the current ones to replace the current functionality are almost Nill.
You don’t need yaml at all. Open automation, click the 3 dots in top right corner > edit name. There you have option for both the title and the description.
Oh wow, many thanks… this is exactly what I’m looking for but it’s an incredibly unintuitive place to find it. I’ll mark this as a solution but I feel that I looked for a way to add a description from within the UI but it never occurred to me to look there and I don’t think most folk would.
I suggest you mark Sir_Goodenough’s first post as the Solution because it was first to explain that automations and scripts have description fields. The balance of the posts focused on convincing you the description field fulfills your FR.
The Description field is literally under the automation’s name.
In the 5+ years I have been helping users, an inability to locate the Description field is not a commonly reported problem.
Sorry, Sir_Goodenough’s post was helpful as I wasn’t aware that there was a ‘description’ field within YAML but it did not resolve my request. If you read my feature request you’d see that I specifically requested that there be an ability to create documentation from within the UI (I don’t know YAML and don’t even want to view it).
My request was resolved by another who pointed out that there was an (unintuitive) way to do this via the UI and I marked this as a solution.
I’m not sure what you are implying when you say ‘inability to locate the Description field is not a commonly reported problem’ but you should understand that I’m a HA noob who is enthusiastic about it but in no way expert. HA should aim to be accessible to users of all levels.
Integrate AI to auto generate all of this. I work for an IPAAs company and we have AI built in that automatically generated descriptions about every stage of an integration from input to output so anyone can come in and understand what is happening
Knowledge of YAML isn’t germane to this discussion because it isn’t needed to create or edit the Description field.
When I showed you a screenshot of just how much documentation you can put into an automation’s Description field, you assumed I must have been done in YAML … but I didn’t, I used the UI (I didn’t even mention YAML in my post).
The Description field that everyone has been suggesting as the solution to your Feature Request, is created and edited via the UI. Knowledge of YAML isn’t needed. However if you want to format the text in the Description field, knowledge of Markdown is needed.
Let me clarify then, contrary to your claim, discovering how to edit the Description field is not an issue for “most folks”. I’m basing that on the 33.5 thousand posts I have read over the past 5+ years.
When you save an automation, you are given the opportunity to assign it a Name and a Description. When you saved your first automation, you probably skipped the Description field and left it blank.
To edit an automation’s Name or Description, you select the Rename command from a list of commands displayed in its overflow menu whose icon, three vertical dots, is sometimes called the “kebab” menu. It’s a common way of neatly tucking away commands related to the displayed context. It’s used extensively throughout Home Assistant’s UI.
While true, the dialog is also presented when you first create and save an automation. But yeah, I agree that description stuffed behind “rename” is unintuitive.
I didn’t find it either, so I guess I’m in the same boat.
But seriously typing into the text field in the UI or typing into the pre-made text field in the YAML editor… I mean there’s even fewer clicks to get to the yaml but it’s exactly the same activity otherwise.
