Beginner friendly documentation

Feature Requests
#21

A lot of the old posts from prior to mayish (might be off by a month or 2) 2020 were prior to the ‘website search’ changes. You couldn’t search the site for ‘default config’ so your fallback was to ask here. That’s all changed now and the search functionality is useful. As for the topic at hand…

Personally, I’m with you on this subject. The doc’s need some love and reorganization. Any input you have is welcome. I’ve always thought we needed a “Getting Started” section that just hammers through the doc’s in the correct order. We also might need an update to the glossary section where we can cover things like “domain”, “entity_id”, etc. Then we can add links in the documentation wherever those keywords are used.

5 Likes
#22

Yes, and no…

This is one of those chicken and egg problems. By the time you know enough, you don’t see the problem any more. It’s only those new to HA who really see these problems.

We need the help of the “newbies” to improve the docs. Sometimes it’s within their ability (edit the docs once they learn), sometimes all they can do is flag it up as confusing.

I’ve mentioned it elsewhere, but the project has reached the point where the docs are primarily a reference manual rather than a user guide. It really needs both, but writing that user guide isn’t a small task and nobody has been brave or crazy enough to pick it up, yet.

5 Likes
#23

I cannot agree with this. I’m a developer so I understand your point incl the difficulty of writing usefull docs by author of the software (for whom most things are obvious therefore doesnt deserve a more detailed description.
But IMO, the developer is responsible for creation of meaningful documentation. One which provide all possible information in as consistent way as possible.

Yes, it’s usefull to engage newcomers after they get grip on the software. But we have situation here in which the person is not able to even to collect basic information to start with because, and let’s face it, the HA documentation is often very laconic, and/or pages to refer terms which are not linked with their documentation. The last mentioned issue is also a reason why it’s far away from reference documentation

6 Likes
#24

Not sure what company you develop for but documentation is almost always a separate department that works closely with developers.

2 Likes
#25

And what if there is no such department? Whar if sf is created by single person, or team of friends who are programmers? Does it turn into no documentation?
At the end a user really doesn’t care about who created documentation. For him it’s software provider/creator aka developer.

3 Likes
#26

Typically in my experience this happens in smaller companies, and the end result is poor documentation that includes a lot of assumed or tribal knowledge and looks a bit like the documentation that HA has.

6 Likes
#27

Then it’s “You get what you get”. Which is where we currently are, managed by the devs.

2 Likes
#28

I think I feel the need to apologize for the others “if you can’t figure it out then move on or fix the docs (even if you have no idea WTH you don’t know)”. this thread really took a bad right turn somewhere.

Tinkerer is at least correct that by the time you figure stuff out then you can no longer see a lot of the issues with the documentation or don’t really want to spend the time to dig in and update it.

If you’d like some help feel free to PM me. As long as you are willing to spend the time to update the docs from a newbie perspective after we’re done I’ll try my best to help you figure stuff out.

8 Likes
#29

I agree with you @microfx, the documentation can use a lot of refinement. I don’t think it’s beginner friendly at all.

It hasn’t kept up with all the improvements to the UI and UX over the last two years. Just from a quick glance, the “Zone” integration docs for example doesn’t mention the Zones GUI editor at all, and that feature is now like eight months old.

There’s plenty of examples like that all over the docs. The Lovelace card pages don’t really mention they can be edited from the user interface, etc… It often makes Home Assistant seem significantly harder to use than it actually is. I bet there’s a lot of beginners following outdated or lacking documentation and actually making things harder on themselves.

Getting started section should be significantly expanded I think. It guides you through the onboarding and creating a basic automation, then tells you about presence detection and that’s about it. There needs to be more there, walk the user through some of the next steps in order as Petro said.

The cookbook/examples need to be updated as well. Many of the examples use random third party services, the “send notification based on sensor” example should use the official Home Assistant mobile app rather than pushbullet. The “automation for rainy days” example uses Dark Sky which new users can’t get an API key for, etc etc.

There’s a bunch of other things that are barely documented at all, even core concepts like Areas. I don’t think the structure is great either. I disagree with the way the “Topics” right sidebar is laid out. It is pushing “Advanced Configuration” and explaining things like Jinja templates and SQL Databases before the basics (Automations, Scripts, Scenes, etc).

IMO the documentation needs a significant overhaul. But no one has really stepped up to tackle this yet. A few people collaborating on this could make an enormous difference. If you want to try and help, I’m sure many would be happy to answer any questions you might have. I would check this out too: Editing the Documentation and Creating a Pull Request on Github.

9 Likes
#30

@finity Totally agree. Although I don’t see a wrong turn. Quite productive conversation here. Not often held. Thanks a lot for your offer. I will definitely do this.

@SeanM Yes, I can totally agree. And I think it is inevitable to start from scratch. There should be Guides that are easily understandable and more or less failsafe – even for my grandmother. With lots of Screenshots and complete configs. It is really not too hard to become good in HA. It’s just the tiny bits of knowledge you all have learned in a few decades of using HA / coding / tinkering with linux etc. pp. and or you are just smart :slight_smile:

What do you think? I am willing to help where I can with ideas, screenshots and writing and the most important extreem noobism :wink: . But I would still need lots of help because I am not even scratching the surface with this super awesome software! Can’t be said enough.

#31

I totally agree. I had a lot of issues as a new user (still some when I try something new). My big issue besides not written for a new user is there is zero document control. I have mentioned it before and I was told that this is to hard to implement. Without this I believe the documentation will never be done correctly.

3 Likes
#32

I also had this issue the first few tries getting HA going. At one point years ago I gave up and learned JS/NodeJS to write my own front end for my Particle devices because that seemed easier (it was fun, but not easier).

Anywho, I’m lovin’ my HA now, and excellent docs are always a great idea.

#33

I have the same experience as microfx and his comparison to Linux is a good one because that’s exactly what I noticed multiple times: documentation is written by and for people that have a fair amount of knowledge of Linux.

To be very clear: I’m stepping in here because I’m very enthusiastic about the discovery of HA, it’s possibilities and I’m aware that A LOT of free time goes into it by everyone that contributes to it, for free.
I don’t want to criticize anyone for how things are done and I always hope that it’s possible to remain constructive.
When you start with HA and have no knowledge of home automation and programming, the learning curve is indeed quite steep and if you’re struggling to get basic things to function, the documentation lacks coherence.

The point is of course: for what kind of people is HA intended and is it an advantage or not to make it more accessible.

Just my 2 cents…

#34

So… I have blogged about my setup, its total opposite of documentation lol, little words and tons of examples. Just the way I like it, feel free to take a look at https://www.freesoftwareservers.com/display/FREES/Smart-Home

1 Like
#35

Would it perhaps be a good idea for 0.116.x, similar to 0.115.x, to be delayed a few weeks and some time invested in a road map and timeline for documentation updates? Maybe getting some feedback from the community on which areas need the most attention? Just a thought.

This is slightly off topic, but I have been meaning to make the suggestion for a while that perhaps release cycles going to 4-6 weeks instead of every 3 weeks would allow a longer Beta, make for less bugs and more time for devs to spend on making sure all the i’s are dotted and t’s crossed, so to speak.

This would include better documentation due to less time pressures of the currently quick release cycles. There is so much to tackle that perhaps it would be a good idea for everyone to slow down for a minute and really analyze how to logically attack it.

5 Likes
#36

@microfx I started here a while ago so I have absorbed a lot, and much has changed over the last few years.

However I found, when I started, that a good idea was to start here https://www.home-assistant.io/blog/2016/01/19/perfect-home-automation/ and then go to here https://www.home-assistant.io/docs/ and read every page.

Yes it could be improved, and it is great to want to help - I have done a little of that myself.

The trouble with a getting started page is that everyone wants something different from their system.

#37

MicroFx- I was where you are a few years ago. If not for the kind hand holding of the experienced users, I would have given up.

FYI- This is the first time in three years that I saw a moderator and an admin post anything. You must have touched a nerve.

And I still don’t know what the domain means in Home Assistant.

#38

I have seen plenty of mod and dev posts!

I think domain is like the category an integration is in, like light or switch or climate. The bit before the dot in an entity_id.

2 Likes
#39

exactly this

2 Likes
#40

I think what is required (or desirable) is an overview or concepts page.

What is home assistant?
How does it work?
How do I add a light?

A general overview page in other words.

5 Likes