I donāt get it. Whatās wrong with Latest Share your Projects! topics - Home Assistant Community (home-assistant.io)?
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.
Well, thatās not for HA, purely for Z2M and unlike the others is relatively actively maintained.
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.
Edit: wrong quote
In case you werenāt aware, the Community Guides section of the forum is a wiki
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
-
@Stiltjack Great Feedback. Let me try to explain
- 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.
Your site mockup does not inspire me. I search for bulb and nothing changes. It even still shows plex.
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.
1 Like
Same on Aliexpress.
And many manufacturers keep the same device marketing name, but the innards or firmware change, making the usually less integrable. It is a nightmare.
1 Like
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.
1 Like
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?
1 Like
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.
āBuild it and they will comeā. Maybe. Give it a go, you have nothing to lose but coding hours.
2 Likes
Yeah I think youāre right. Iām gonna keep updating this and see what the feedback is and if it gains any traction.
1 Like