I like the idea. But I also see the scale of the project, in both development and, more importantly, ongoing maintenance.
Frankly, I think this is the root of the problem. Developers are good at developing, and they enjoy doing it. For most, documentation is no fun and it’s not a skill which comes automatically with the ability to code. It’s notoriously hard to get paid developers to write good documentation. I can only imagine what would happen if you tried to force unpaid volunteers to do it. I don’t have a solution. Rigid documentation standards which required all the information the OP wanted would take yet more volunteers to enforce and drive developers away.
With my note on responsibility I was referring more to the idea of @nickrout to “integrate” it into the official documentation. Like adding a list of tested working devices to the page of the integration thats needed. I like this way a lot if the search within the docs cover this and a user would be able to search for the device/model to see if it works.
On the other hand, a wiki topic where every user can add tested devices themself is also a great idea.
Thinking about this, I’d prefer a combination of both maybe? As the community we could work on the wiki topic here and in the documentation there could be a link to the list. So it is dynamic in its nature but also bound to the documentation somehow where new and interested users can find it easily.
Hey, sorry for the slow response, I have been working on that during my vacation and have been travelling back the last 2 days.
Thanks for your great feedback. I won’t be able to touch on everything tonight but here are a few quick thoughts:
@nickrout The community aspect: This is of course the big thing. If no one is willing to help, this won’t work. But as with most projects like these no one person can maintain this so IMO this is the only way. And depending on what community evolves around it, it will be its biggest strength. So I won’t worry about it now IF enough people are willing to help. Depending on the page setup, you could probably increase engagement by incentivising community engagement
About the content, I don’t see it that every brand and every documentation page has to have a corresponding entry on this site (yet). And sometimes it is also not really necessary. i.e. for real & play integrations
Thanks for your offer, pdscode. Moderation is a concern of course but also not something I would worry about in the begging. About the specifics concerning that, as I said the site is largely a prototype and before I move on I want to have this feedback to steer into the right direction. In other words: You still can request changes
Concerning the official documentation I don’t think that is the right space for tutorials / device specific information or information on how to purchase these devices
As I said, you wouldn’t need an item for every Integration at first. The added value comes from the first integration
I’m thinking of something like matacritic where you can vote on based on your personal experience. With a big enough sample size this should give you a pretty good idea on what to expect when you want to try that integration.
Concerning the forum points, I know that these things exist but they are buried here in the forum and if you don’t have the right search phrase you are never gonna find them. The idea is that the relevant information is bundled around the device that you are interested in. This kind of structure you can’t get in a forum
Blueprints / Automations / Config: Same thing - you can find all these that are relevant for the Integration you are looking into right now. You don’t have to accumulte them by yourself. As a kicker I would see if there would be an endpoint where we could import the stored YAML files directly into an automation or the config (if there is no UI yet)
What’s your point about purchasables?
That is exactly what I’m trying to solve! The finding part of the information. We don’t necessarily need a lot of new content
In essence we don’t have to reinvent the wheel here concerning the content. There is a ton of it already right here. Just tying it together is the issue. In the simplest case we could just link a bunch of helpful guides and topics directly from this forum.
If you want me to implement anything to help you jog your imagination, feel free to tell me. That said it is still a prototype. Don’t expect a lot of functionality.
Being a bit glib, sorry. I have noticed that many sellers (Amazon, for example) keep their listing even when a product is out of stock - I have clicked on links here in the forum a number of times only to find that there is nothing available. Keeping track of where devices are in stock and at what price is a major undertaking in itself. Also, where are we talking about? US, Europe, Australia, Far East?
Quite right. So how about starting with a community guide to web resources? It’s something we need - even just a list of reliable YouTubers would be valuable. As @nickrout points out, each post there works like a wiki, so you’d get a feel for how many people might be willing to contribute to a larger project, possibly even identify individuals to join your team.
A lot of truth there (do I detect the voice of bitter experience? ), but a very broad generalization. Some HA developers do manage it. A few HACS integrations have good documentation - Entity Controller, for example, where the developer uses MkDocs to create a very clear navigational structure.
Looking at the Home Assistant docs, the root pages are similarly quite clear, with a well thought out list of related topics in the side panel. This falls apart in the integration pages, where the side panels don’t contain links to other topics at all.
How can we improve this?
Sure enough, in the Community Guides there is a wiki on how to edit documentation…
It has been a great improvement to the integration documents in the links to the source code and issues relating to the integration.
One area people fail to understand time after time is the “generic” integrations, eg for a Sonos integration you also need to look at the media Player docs, ie Media player - Home Assistant
The generic instructions have all the stuff that pertain to all media players, or all lights etc.
Good point. Yes, a very broad generalization, but one that’s not unearned. I’ve seen some great documentation here. The Google Drive Backup add-on comes to mind, but there are many examples.
And, admittedly, the documentation is never going to be perfect. It’s a moving target, and the resources just aren’t there to maintain the huge body of knowledge needed to cover everything you can do with HA.
Bitter experience? No. Experience, yes. And an understanding of the underlying dynamic.
I think you don’t understand what I mean by prototype. It’s just the looks, no functionality. Just assume the search works. It’s import what you would like or what you expect from it.
No worries hehe. I understand what you mean. Of course the product availability is a big issue but I don’t see a way around it. It’s the way it is. I mean that problem is the same with any product link you post. And for that matter also a lot on the internet. Just that in the case of retail the changes are very often. I would approach this by making it possible to mark the purchasable is discontinued / out of stock / etc. But if you happen upon a purchasable that is actually available it’s an automatic win. The market would be a property of the purchasable. Maybe along with the price
Hm, not sure I follow. You mean a post inside that category here in the forums? I can’t really contribute a lot there since I don’t have all the resources. Or do you mean so others contribute? But if that is needed and it is so easy, why is it not being done?
IMO more effort needs to be spent on making it easier for people to acquire the right smart home devices and make it possible to set up and use their integration effectively. That is a big aspect of user retention
where do I get it?
how do I set it up?
how do I create useful automations?
if I have issues, is there someone else with the same problem?
Yup. In other categories you can add comments replying to the original post, but only edit your own. In the community guides category anyone can add to the original post, like a wiki. Click on the pencil symbol top right.
Edit: Actually, I see you have to be a Level 2 user to edit a wiki item. There’s a rundown on the “Trust Levels” here:
Hm, this does not seem appealing to me. I think the the option of having a site that I can adapt in any way is much more versatile.
If the wiki is something that is of interest to people then someone else can do it.
I think this is a good discussion that is happening in here but it is a little off topic and I would like to bring it back to the feedback part about the idea itself.
), but a very broad generalization. Some HA developers do manage it. A few HACS integrations have good documentation -