Beginner friendly documentation

Feature Requests
101

Thanks! Having already arrived at home assistant from a commercial product, I found some of the posts in particular a little alienating.

To me home assistant is a breath of fresh air. Previously if my vendor issued a software update I would leave it for a month to see what it screwed up, then leave it a bit longer.

Home assistant update, hell yes install it, nothing breaks, nothing bricks the hardware, oh! and it gets faster and uses less resources.

About fifty years ago I wrote software, we documented our own and gave it to our users to break. If they couldn’t understand my documentation they soon bloody told me.

The comment “Its documentation reflects the people using it “ I found particularly odd, does that mean the people using it are not very good and crap in parts? Why shouldn’t we aim for to something be proud of, documentation included?

2 Likes
102

Nobody disputes that the documentation could be better.

Name a particular topic that you think is wrong/missing/confusing/in need of improvement, and I and many others will be looking into it.

103

This is but one of several possible ways to automate your home. It’s the one I use alongside another I have used for over a decade. Despite the thousands of posts I’ve created here, I have no fanboi allegiance to this product.

Exploring other solutions broadens one’s understanding of home automation. One might find something that’s a better fit. Alternatively, one might return to Home Assistant, potentially with fresh ideas borrowed from other products. It’s a worthwhile journey.

For example, the openHAB team is working towards a major new release at year’s end. Part of that process includes an overhaul of their documentation’s introductory content. Lead developers post drafts in the community forum to allow members to review and comment prior to release. This ensures new and experienced users can shape the content before it is officially posted.

104

Do you know if anyone has floated a documentation guide as a template for creating a baseline for the devs to follow when they write their docs?

105

While having a template is good it may also serve to put off devs doing stuff, if the template is so overwhelming and requires everything to the nth degree and potential dev may say, nah to hard and not integrate whatever they wanted. we have to remember a lot of people do this in spare time, forcing them to do more may put them off
just something to consider

there is the standards guide also

2 Likes
106

Here and the subsequent pages is what I found https://developers.home-assistant.io/docs/documenting - not a template, but standards. There are templates for sections in a page.

1 Like
107

Wow. What a refreshing thought. Actually listening to users, and treating them as valued contributors. Almost as customers. I looked at OpenHAB but ended up selecting HA. Overall I’m very happy with my decision, but this is apparently one area where OpenHAB has a leg up.

108

A huge improvement would be to add more screenshots!

Having sample configurations in the documentation is nice, but an additional corresponding image from the result in the UI would make life way easier! (Especially for non-native speakers.)

3 Likes
109

While I agree with this in general, the problem is maintenance of these screenshots as HA is moving so fast at the moment.
E.g. a new integration is added and configured through the UI. Now you create screenshots and make a nice tutorial. Fast forward 1 month later, new options have been added to configure the integration through the UI, which means taking new screenshots and so on.

2 Likes
110

@aidbish & @nickrout, Thanks! I’ll take a look at these.

111

Hey all, I’m also totally new to HA and found the docs super hard to understand (even as a programmer). There’s a bit of a chicken-and-egg problem, which is that once you know about HA, it’s hard to write from a beginner’s perspective.

I hope this can be the start of bridging that gap. I put together a “mad libs” style outline of the docs I wish I had, take a look.

Comments are open, please feel free to copy/paste/remix freely. I can also convert this to markdown and submit this as a PR, though as you’ll see it’s very incomplete.

1 Like
112

Excerpts from your document:

Devices
Home Assistant calls the smart devices in your home Devices. An example would be a Hue lightbulb, an automated garage door opener, or a motion sensor.

Entities
Instead of automating devices, people in Home Assistant usually talk about editing entities. An entity represents some function of a device, like a single sensor or a single switch.

Two definitions, each defining a different concept, yet both use the same example: a sensor is a device and an entity.

Shimmer, it’s a floor wax and a dessert topping. :wink:

You didn’t make a mistake; you identified one of the aspects of Home Assistant’s evolving terminology.

In the beginning, there were only entities. A light bulb is a physical “thing” and is modeled as an entity (whose domain is light). If you have a physical “thing” that reports several properties like temperature, humidity, and light level, it is modeled as three separate entities (whose domain is sensor). However, there’s nothing to refer to the “thing” itself. As a result, there’s no means of showing the three sensor entities belong to a single physical “thing”.

The concept of devices was introduced as a means of identifying a “thing” and all the entities that are part of it. You have a multi-sensor device with three sensor entities reporting temperature, humidity, and light level. The same concept also paved the way for device automations.

For example, here’s an ecobee switch+ device with several entities. I can easily create device automations for it from its Device view:

Screenshot from 2020-09-17 00-04-33
Screenshot from 2020-09-17 00-04-331022×689 38.8 KB

If I look at the Philips Hue bridge device, it shows no entities.
Screenshot from 2020-09-17 00-07-30

Each Philips Hue light bulb is shown as a separate device. If you examine the device, it shows it has one entity, a light.
Screenshot from 2020-09-17 00-12-42

So in this example, a Philips Hue light bulb is both a device and an entity.

Summary

  • A device represents a physical thing.
  • A device may have zero or more entities.
  • An entity is typically a property of a physical thing but can also represent the thing itself.
5 Likes
113

That was a GREAT explanation. I think even I understand it now. Thank you!

But you sent me down a rabbit hole of SNL sketches on YouTube. Some great laughs, but there’s a half-hour of my life I’ll never get back!

1 Like
114

Thank you for reading @123! I updated the doc based on your explanation, hopefully it’s clearer.

Would love feedback from anyone else on the other missing pieces!

115

Your document’s definition of a Zone isn’t quite right. The definition of a zone can be found here. It’s a geographic area, typically used by a device_tracker (i.e. trigger an automation when you are detected to be approaching your home).

What your document describes (“rooms in a house”) is an Area. Currently, the concept of Area is underutilized and simply represents where a device is located.

116

Your definitions in the category Home Assistant Software are incorrect. Take a loot at the excellent overview that Taras created for the different install methods.

Supervisor is not only there to keep it all up-to-date, it’s also responsible for handling add-ons, backup and restore etc. You can find more details here.

117

Updated! Thanks @123.

This is exactly what I was hoping for. I think writing wrong documentation and waiting for it to get corrected is actually a decent way of getting documentation done :slight_smile:

118

@Burningstone thanks for the correction! I’ve updated it, is that better?

For others who might read this, I’ve highlighted the terms that seem important but weren’t clear to me from the glossary–suggestions very welcome.

119

@microfx @stevemann @nickrout @petro you might be interested in seeing this “HA core concepts” documentation. I would love your help writing/correcting it.

120

It’s better but I don’t think it’s a good idea to have links to forum posts or developer docs in the official documentation. Either a link to a separate doc page (non-dev doc page) or explain it on the same page.