Hey, not sure if this counts as “small”, but there might be small things that could at least ease the pain. I started out with HA in February, and most of what I wanted to put in place actually does work in the end. But: for almost everything that went beyond the outofthebox stuff, it was a painful search through official documentation, the forum here, external blog posts, amazon reviews (!?!), youtube videos, andandand, until I had everything working. Sometimes the official documentation points to paragraphs on the same page that don’t exist anymore, sometimes there is this one tiny yaml adjustment that turns a noisy mess into a working display, sometimes a youtube video quickly pans over a HA config screen where I can detect the missing checkbox, or I dig into the actual codebase of an integration in github to understand what this one weird parameter ACTUALLY does, andandand.
HA is so powerful, and in the end actually straightforward, but without a more consistent documentation or knowledge management it relies on persistence across various sources, and a portion of luck, and therefore self-limits its potential in growth and impact.
Potential solutions or building blocks:
extended tagging options (e.g. proposed tags, similar to “your topic is similar to…”
a forum section for “this is how this one thing worked for me” sharing (“Share your projects” in smaller)
“documentation updated?” review as a must-have for new releases
Happy to elaborate on this one if there is interest.
Don’t get me wrong, I’m hugely grateful for what HA and the community does, but I already have a background in IT, software etc for 20+ years, and still sometimes understand why people in my surrounding just go for the less powerful but better documented solution from the hardware store next door
I would say the biggest reason for HA users to struggle their way through documentation is because the user that has just gone through exactly the same difficulties, did not go back to the official documentation and update it. I have personally updated documentation and it’s straightforward, there’s also options to make suggestions or provide feedback but, equally, I have also found the solution to a problem and not improved the documentation so I’m just as guilty.
Extended tagging options seems a great idea, especially for youtube videos or tutorials (maybe that is already possible I’m not sure). At least the updating documentation aspect of HA is something we can all contribute towards and that’s not implying that you don’t/wouldn’t, I’m just making mention of how much improved the documentation would be if we all made that concerted effort to go back and update (I’ll certainly see if there’s anything I can after writing this ).
While it’s true that most users don’t go back and suggest updates, it’s easy to get discouraged from helping with the docs when multiple users have submitted PRs and dumpster fires like this go basically unfixed based on technicalities that do not matter to the users who are trying to figure out how to use the function.
You call it a dumpster fire, I call it pushing for the right solution. The result is that there is now a PR pending that is almost done and might even make it to 2022.10. We should fix things, not document workarounds.
“…is because the user that has just gone through exactly the same difficulties, did not go back to the official documentation and update it.”
I really struggled to find sidebar options when the view was released and attempted to edit the docs so others wouldn’t have a hard time, but my PR was rejected. It’s possible my PR didn’t make sense or I added the info in the wrong section, but instead of relocating the info or recognizing that the concept was confusing, the PR was closed and the clarification was not added.
This happened so long ago that I don’t recall the details, but believe that in general the HA docs are hugely limited. I frequently need to look elsewhere to understand how to use features.
I call it a dumpster fire because it’s disorganized, causes a lot of confusion, and the “we don’t document workarounds” logic is not consistently applied…
A: We don’t document workarounds.
B: The need to use “or” is in the documentation.
Conclusion:
The need to use “or” is not a workaround. As such, the documentation should be fixed so that is stops causing so much confusion for new users.
Don’t get me wrong, I’m glad the underlying issue is being addressed. But when that goes through the docs are still going to be confusing because they are not internally consistent.
But just imagine how much improved the documentation would be if even half the community frequently updated the docs, especially new comers, who see the current issues. It’s a shame your suggestion wasn’t implemented, the dev themselves originally worded the docs in a way that didn’t quite make sense, or you wouldn’t have had a problem, so there’s never going to be a 100% fix. One thing’s for sure though - no individual is going to review the HA documentation and bring it up to a state we can all find acceptable, it’s an open source project . If we’re going to highlight a problem, there needs to be a sensible solution and the solution to this particular problem is for the community to step up and improve the docs, even if it’s a suggestion of what to improve.
If i can add my 50 cents here. I was recently searching the documentation for “schedule”. No chance. I landed on integration such as Renault.
It took me some time to realize that i need to surf to the integration page to find the schedule info.
At minimum, the search engine should be deeply revisited.
I think this gets to the crux of the problem. It should be easier, and actively encouraged, for users to suggest edits. GitHub accounts and understanding PRs is probably quite a big hurdle.
Then there’s stuff that is probably too specific for the docs but you think it is likely that someone else is going to try and do (I use public Gists for stuff like this). E.g this. (as much a note-to-self than an act of kindness) Adding Tradfri Devices with ZHA on Home Assistant · GitHub.
And someone else who listens to the feedback. It’s a little bit sobering when you make the effort but the feedback goes nowhere and is at some point marked as “stale”.
I agree, it is not always nice to see feedback not being addressed, but the reality is: This is an open source project, which relies on contributions made. Things do not magically get resolved or changed, this requires someone that contributes
So, by all means! Feel free to suggest edits (instead of providing feedback)
In my opinion, the problem is not (just) the insufficient and inconsistent documentation.
It is the structure in the material.
For example,
entity Sun, which has been in HA since pre 0.7. No explanation how “offset” works.
the constant moving back and forth between yaml files and UI when explaining something is confounding.
Finally, lots of specialized, “Home Assistant” language used throughout the documentation without easy access to explanation.
e.g. What is a “Dashboard”?
Home Assistant dashboards are a fast, customizable and powerful way for users to manage their home using their mobiles and desktops.
That is conceptually makes sense, but where is it on my screen? How is it manifesting? What does it look like? How can I distinguish a Dashboard from a non-Dashboard? Same with card, entity, etc.
Is there a wiki out there? Maybe I will kick one off…
I’d have to agree that in many cases I have tried to follow the official docs to work out how to code the specifics of a particular trigger or something and the docs simply do not provide an example of all the optional settings and thus I struggle to work out how it should be done.
eg: Trying to create my first template select using the fairly new template trigger system. The example for the template select is somewhat lacking on explanation on how it all works.
There’s an edit button at the bottom of every single page in the documentation. The documentation is basically a wiki with a more formal review process for changes.
It is also important to put in the right amount of documentation and not explain things too much. Otherwise, more confusion and questions may arise that do not always need an explanation or answer.
One suggestion I heard was to explain config_entry format in the docs for an integration for those that do not use the UI to write automations. The UI already does the job for you. The old saying is still true today, keep it simple stupid.
).
. If we’re going to highlight a problem, there needs to be a sensible solution and the solution to this particular problem is for the community to step up and improve the docs, even if it’s a suggestion of what to improve.
