Improving HA documentation?

Feature Requests
1

I had meant to create this topic in the month of WTH, but it appears I got to it too late and new topics are closed there. I only have myself to blame for that :grimacing:

To me, the most important feature request is not in functionality, but rather documentation standards. As a developer myself, I know that no one likes having to put aside extra time to create and maintain documentation for the software they’ve created. Furthermore, it can be a thankless task because documentation gets obsolete very quickly and the maintainer gets blamed for it.

Nonetheless, as powerful and feature packed as HA is, it suffers badly due to inadequate user documentation that is also not comprehensive. I point this out precisely because this makes it difficult to appreciate the hard work HA’s contributors put into the software and use it to it’s full potential and thus expand HA’s user base.

Before I decided to switch over to HA from Indigo, which I had been using for almost 10 years, I had read warnings from users to prepare for frustration in HA’s learning curve. That seemed silly because HA looked very user friendly on the surface.

The reality is, it has a huge learning curve and it’s a painful process for new users to understand how to get it to do anything beyond switching on a light. This is evidenced by the large volume of confounded users in the forums here. Seasoned users do not notice this because they are used to the HA ecosystem.

In my opinion, this problem could be drastically improved with more complete and comprehensive documentation. For instance, if I am a new user switching to HA from another platform, and right off the bat I need automations that depend on a device tracker, I may follow the easy steps of flashing Hassio onto an SD, fire it up and get instant gratification when I see Lovelace for the first time. I’ll be thrilled that I can just tap through the menus and see a wizard for creating an automation, and expect the user interface to walk me through the steps of triggering something when I arrive home. I see an option to trigger on ‘Geolocation’, but don’t know how that is set up.

Then search for device tracker in the docs, and find this page:
https://www.home-assistant.io/integrations/device_tracker/

While none of the individual pieces of information on this page is inaccurate, the information is so sparse that a new user may up being more confused after seeing the page than if they hadn’t.

For instance, after the two sentence description, the very next thing is a configuration snippet for a netgear configuration, followed by some esoteric information about configuration parameters.

There are no links other than ‘home zone’ on the page to any other documentation that would explain the very large number of HA concepts that are a prerequisite before the information on this page is useful- so at a glance, as a new user I need to understand:

  • What is a platform?
  • What is configuration.yaml? May be obvious to someone who has done any customizations at all, but what about a new user who has only seen Lovelace?
  • There is an example for netgear platform, what are all the integrated platforms, and do they all use the same parameters and behave the same way?
  • What is a service, and how can I use the one described on this page?
  • What is known_devices.yaml, and what purpose does it serve in HA? Also, why does one note describe current behavior with it, and another note say it is being phased out? Even more confusing is the large number of community posts that mention this file and troubleshooting it.

Finally, even if I understand all the above, what is a device tracker’s behavior in HA? If a device tracker’s status shows a particular named location or ‘stationary’ on a person’s banner icon, how do I know whether that means home or not home in HA?

I’m just using device_tracker as an example here, but that one was a particularly frustrating experience for me to learn more about it by reading other users’ struggles with it than from HA documentation of this core concept.

Given that making good documentation can be time consuming, especially if you want to provide a complete set of examples and recipes that work and are up to date, perhaps a more ‘wiki’ style of documentation could work? One where users in the community have the ability to easily submit amendments to the HA documentation for approval by a developer or moderator?

2

It’s pretty easy to do just that and there’s an excellent guide here.

1 Like
3

Yep thoroughly agree.

I’ve just started using HA and found the same thing, the initial learning curve is really steep, I found a good guide outside the HA community (https://siytek.com/home-assistant-automation-tutorial-for-dummies/) but there ought to be something similar in the HA user guide.

I also found that when you do start doing more things, you soon find issues or important details missing from the documentation which you need to go searching the forums for, only to find lots of other people had the same problem, but the documentation never gets updated.

I wondered whether the answer was a specific forum section, for new users or those less knowledgable about the detail to post documentation issues, errors, or missing information to allow those with a better knowledge of the platform to update the docs with the correct information.

People suggest using Github but as a new user while I can see the problem, I don’t know enough about the platform to know whether the solution I’ve found is the correct or best one, it needs more knowledgable users to do that.

This was my suggestion:
https://community.home-assistant.io/t/new-forum-for-documentation-requests/231117/4

4

And tom already answered to you in your suggestion that there is a diwcord channel exactly for this.

5

From the perspective of a new user, it doesn’t seem to be working because otherwise the issues which people are picking up in the forum questions and queries, would be going round the loop and getting the documentation issues fixed.

Besides, why are there different channels for essentially similar things? We’ve got this forum here for feature requests, why isn’t that going through the discord channel?

If you have a forum for new features, seems perfectly logical to have a forum for documentation issues, we could even vote on which areas need the most attention like we do for the new features?

6

I’ve previously noted that the documentation is more like a programmers reference manual than end-user documentation. It’s stuff that’s definitely needed, but there needs to be something layered above that to provide an overarching “solution”… basically a recipe with all the steps and complete/complex examples.

Yes, because as many newer users have complained about over the past few years, many of the third-party guides are never updated and eventually become misleading/unhelpful.

7

Thinking more on it, perhaps documentation of core features and integrations would be better managed by those close to implementation (code) of them.
-but perhaps a better way to make the documentation more comprehensive and work better would be to allow the users to contribute just the recipes that demonstrate the feature. This could appear alongside the ‘official’ documentation, each recipe maintained logically as a child of the feature documentation, but maintained separately.
I don’t know how HA developers typically test their functionality, but this recipe pattern could be leveraged and automated in a continuous integration pipeline where possible. This would also make releases much more stable.
I know I’m getting a little lofty here, but stability also seems to be an issue with users commonly reporting things breaking with each new release. A CI pipeline that regression tests all of HA functionality seems like it should be a priority.

8

My impression is that the there is considerable automatic low-level testing already being done (i.e, I think most integrations have their own test).

Someone would have to go analyze, but I think (well, assume) that the breaks are distributed across a number of causes… some of them third-party related, others are from situations that weren’t originally conceived of, and others are corner cases. I’ve seen plenty of times where they go back and improve the automated tests to cover the breaks.

9

From my experience most of the people with “stability” issues didn’t read the release notes at all and just blindly update. I can’t count anymore how many times people posted issues with a release and just reading the release notes BEFORE updating would have solved them.

10

From my experience most of the people with “stability” issues didn’t read the release notes at all and just blindly update. I can’t count anymore how many times people posted issues with a release and just reading the release notes BEFORE updating would have solved them.

To a degree it’s fair to say that users should move to a new version at their own risk. But over the past decade, users have become accustomed to makers of major software applications and operating systems encouraging them to make sure they’re always on the latest version. In fact, it’s common for subscription based platforms to do this automatically. Some won’t even assist with technical issues unless the user is on the latest version. Not saying HA is just like any other software platform, just that it’s not reasonable for the user to be notified frequently of new versions when using the software, evangelizing new features, functionality- and fixes- and expect them to dive deep through the list of changes and try to evaluate whether or not it’s safe to upgrade.

Stability I think would go a long way in establishing HA as a reliable home automation platform for the masses and less like one that is just for those that like to tinker.

11

Exactly and security vulnerabilities are such a big issue that not updating software and the OS is now seen risky behavior, if a new update comes out then you install it.

12

Your are talking about mature, commercial, non-beta software products, but Home Assistant is still in beta and open source. You can’t compare that.

I’m sorry, but yes it’s definitely expected from the user to read the release notes INCLUDING the breaking changes that affect their system. You don’t need to read all the changes, just the one for the integrations you use. Lately this has become really easy, as the breaking changes are an expandable list group by integration.

13

It’s perfectly reasonable to expect a user to do all that when it comes to Home Assistant. Why? Because it’s a rapidly evolving project that hasn’t yet released its first major version (take note of the leading zero in 0.115). Another clue is that every single release includes breaking changes … and there are releases every three weeks.

Anyone who thinks otherwise, is ripe for learning about it “the hard way”.

1 Like
14

The project has been running for 7 years and it’s still on version 0.115, if it hasn’t released a major version in that time then the project’s culture and approach to version numbering means it probably never will. Linear extrapolation of previous progress would have version 1 arriving sometime around 2070 !

Even a rapidly evolving project should be able to produce stable major versions periodically.

15

What is not stable about the releases we get every 3 weeks? Most of the time people here on the forum say HA is not stable, where in reality they use a custom component that is not supported or the integration broke because a manufacturer changed his API, which is out of conteol for the devs.

16

I don’t mean stable in the sense of it crashing, I mean stable in the sense of having a major version with a defined set of features, operations, commands etc, which is a stable platform which is maintained through to the next major release. With future updates to that major version limited to addressing any specific bugs, problems or other minor issues but without introducing significant breaking changes or other major changes to features or functionality.

Most software operates like this because periodic updates are needed to address bugs or security issues, but these updates are limited in scope because you don’t want a security update or bug fix to break your software or configuration.

17

You said it yourself, it’s been 7 years without a major release, so it’s clear that this project doesn’t fall into the category of “most software operates like this”.

The upside is that this software improves much faster than similar products. The downside is that some of the improvements are breaking changes and the community is expected to adapt (every 3 weeks). That means you must be aware of an upgrade’s impactful changes otherwise you may find yourself with a malfunctioning system.

The people who have home automation as a hobby just roll with the changes. The people who just want a home automation appliance that they can blindly upgrade … have picked the wrong product. The goal is to make Home Assistant consumer-friendly but it’s not there yet. Currently, it’s better suited for hobbyists and tinkerers.

1 Like