Suggestions for improving HA documentation

[RangerZ]

I am a noob shopping for a Smart Home solution. I was drawn here because I can run HA stand alone, however as a noob I am having trouble understanding the big picture around HA.

The home page looks good, but I feel has little practical information.

The getting started page jumps right into loading software.

The Components page offers me little product info other than some sample scripts (important, but not there yet)

In between is the need to move me from “Prospect” to “Customer”. I have spent a lot of time on the forum trying to weed through posts to find answers, but it’s tedious and I am not finding what I want in a concise format.(Thank you again to those who have supported me)

I would like to make 2 suggestions to the powers that be for filling the gap.

1 - I see a need for a few pages of content (Framework) prior to installing the software that lead the Prospect through things like architecture (how Zigbe, Z-Wave, BT and WIFI) work together or not, hardware pros and cons => selection (Why is a Raspberry PI better than a NAS, PC or VM), data architecture (What are the important data files, where does the processing occur for video in particular and how does this impact hardware selection), Terminology, Talk up security (stand alone, remote and messaging) and how this is better than the cloud solutions. Router config concerns) , discuss phone and tablet capabilities etc

2 - Extend the information in the Components pages with more product details (as opposed to just code) so a user can better understand what works with what (ie what are all the WIFI Light bulbs). There are 90 sensors, and even reading the descriptions it’s not clear what many can do (Application below).

Below are some field values that I think make sense, at least for hardware:

• Item Description
• Vendor
• Vendor Part Number
• Vendor Web Site
• Vendor Downloads
• Hardware Revision
• Firmware Revision
• Dimensions
• Power Source (Battery, cable)
• Power Type (Voltage)
• Supported as of HA Version
• Group - From Components side bar
• Application (multiple)
• Supports

1. • Zigbee
2. • Z-Wave
3. • WIFI
4. • BT

• Market
• Picture(s)
• Notes:

Ideally the above should be structured data that can be queried. I think that group, application and support would be the most valuable for finding a device

I realize for those of you who know this sounds trivial, but for those of us who have no clue, this is big.

[zarthan]

Sadly, it takes people to do this. People who have enough time, energy and stamina to carry it through.

[seanb-uk (Sean)]

It’s the nature of an open source project that the documentation will be technical. Writing good end user documentation is a skill and very time consuming. Most people involved in the project will be more interested in contributing to the code as that’s where their core skills lie and it’s what they find interesting - remember, it’s something they do in their spare time.

So the stock answer is get involved! Now you’ve got more experience, contribute to the documentation if you can.

That said, what I found lacking was examples - the examples in the official docs are very brief and don’t always help when you want to do something specific. I’ve had to piece together my knowledge from the (really useful) example configurations, the forums and a lot of trial and error. I enjoy the challenge, but I can appreciate how it can put newcomers off.

I’d like to help with the official docs, but I know I don’t have time. What I do is blog about my adventures with HA, with a fair amount of technical detail. I hope, in some small way, it helps to contribute to a wider ecosystem of information available.

[danielperna84]

Starting this with a possible giggle:

1. and 2ish: The problem is, that a lot of products implement their own way of doing stuff. Even though there are certain protocols that multiple vendors use, they still work different. For ZigBee there’s the IKEA way, which, as far as I know, is fully offline. Same goes for the ZigBee module for the PI. The Philips Hue bridge works offline too, but I at least have the feeling it still somehow depends on cloud connectivity. Then there’s Osrams Lightify, which is directly aimed at the cloud.
   The point here: even thoug it’s just one protocol, it can be this and it can be that. It really depends on the product.
   There’s a blogpost that explains a little bit about how HASS classifies the different methods to communicate with the products. Focus on the green box somewhere in the middle. Most of the component documentations (e.g. ecobee, Philips Hue) are labeled with one of these classifiers. So for the case that you already know which product you want, it’s easy to lookup how communication is handled in that specific case.
   It would indeed be beneficial if the components page would allow to query / filter for this information, displaying only components that match the desired criteria.
   What I would consider very informational for beginners would be something like a 2-3 minute video that quickly showcases HASS and how it works, possibly also mentioning the classifier-topic. I imagine this to be like a typical product-video with animations, not a guy clicking through the UI. More like a presentation with pictures and flowcharts. Or maybe like on of those: https://www.youtube.com/user/minutephysics

2. and 1ish: This heavily depends on which documentation you look at. Some just cover the minimum of information required to get things running, some explain everything in more detail. The more time the developer takes, the better it gets. However, the developers often spend a lot of time improving the actual component (which they should) and leave the documentation behind. Which is kind of ok, since at the current state (consider HASS to be more like a beta version) HASS aims more at advanced users with at least some experience at home automation. It’s by far not the easiest solution to automate your home, but instead a very flexible one if you’re willing to get your hands dirty and know what you are doing. Hhmm, losing the focus here…
   What I’m trying to say, the developers invest their time into improving the code, which is a good thing. Documentation could be done by regular users IF they wanted to. Apparently most do not.
   Regarding all those product details: even though HASS aggregates a ton of devices functionality-wise, it’s out of scope to also include such a huge amount of details that usually can be found on the web with a quick search. Some implementations may only add support for a couple of the devices. But there are others that cover hundreds, and by using MQTT + ESP 2866 there could be a gazillion different “products”. Hence my personal opinion is, that the details about specific devices should be kept outside of the component documentation for the most part, since those details may actually change over time. Vendors (at least in some cases) improve their products. That would easily result in outdated information. Nobody could and would keep track of that. And most importantly: just very few people would actually require that information, and if they do, they can find it on the web.
   On thing that may help in the future might be some telemetry data. If I recall correctly HASS introduced an opt-in feature to gather data about the used components. This would allow to provide popularity-information, thus giving the users an idea which platform is used often and may be supported better than others.

[silvrr]

You can improve the docs @RangerZ.

Editing the Documentation and Creating a Pull Request on Github

I have seen a number of people complain about the documentation at https://home-assistant.io/ (HA site). Great news! Everyone can edit it and provide improvements to the documentation. Next thing I likely see is that people don’t know how to create a pull request on Github. Great news! Here is a tutorial on how to do it. First go to https://github.com/ and sign up for an account. Its quick free and easy. If there is a need for a tutorial for this too, please post that feedback below. O…

[ReneTode]

@RangerZ

that lead the Prospect through things like architecture (how Zigbe, Z-Wave, BT and WIFI) work together or not, hardware pros and cons => selection (Why is a Raspberry PI better than a NAS, PC or VM), data architecture (What are the important data files, where does the processing occur for video in particular and how does this impact hardware selection), Terminology, Talk up security (stand alone, remote and messaging) and how this is better than the cloud solutions. Router config concerns) , discuss phone and tablet capabilities etc

hardware pros and cons are depending on the view from people. a pro for someone can be a con for another.
i dont think the people developing HA should tell others what hardware is better or not, that where the forum is for where you can talk with others to decide what you buy. (most people have bought before starting HA anyway)
there is no better in the choice between RPI, NAS, PC or VM

explaining processing for video before installing? that would be several pages for all depending platforms and not interesting for people who dont want anything to do with video

talk up security and how this is better then cloud solutions?
again asking for a judgement call from the developers. also in this topic there is no better, just a choice.

Extend the information in the Components pages with more product details

i think at some pages a little more helpfull but what you are asking for is way overdone.
vendor is almost anytime mentioned with its link, but part numbers, vendor downloads, hardware, firmware, power source, etc. are abolete, unless some types are not supported and some are.

HA is not a list that tells you what to buy and what not.
if you want to buy a specific sensor for a reason, you go and find out what would be the best sensor for you.
then you go check if it is supported in HA.
if yes, then you can buy it
if no, you can create (or ask to create) a part that integrates that sensor or you could decide against buying that sensor and look for a simular sensor that is supported.

i would be sad if HA became a platform that tells people what best to buy and why a certain way would be best.

[dmiddlet2005]

I agree the documentation is confusing at times. I for one learned a lot of what to do and not to do (mostly by accident). What I would suggest for anyone who writes any documentation/process, etc. is to list out any dependencies and clearly identify whether something is specific to one platform or another or one application or another. Can’t tell you how many times I saw “run this command” only to have it fail because I didn’t know you needed this other thing installed first, etc. I am sure much of this will make more sense the more I do things, but not quite there yet.

Using the field or tag values would definitely be helpful.

This simple step at the front of the document would have saved me numerous troubleshooting efforts (and several reinstalls to figure out what I did wrong).

I still have a long way to go to learn even half of it, but please folks… don’t expect others to automatically know what you are doing or what is required before starting. This is one of the best and most helpful communities around, let’s remember not everyone is as experienced as you.