WTH is there no consistent documentation concept?

Month of "What the heck?!"
41

I’m just going to throw this out there… I’ve been using HA since 2017… I have only ever used the official docs and the community forums… (unless it was a Linux OS type issue) (or the GitHub for a specific custom component) I don’t use YouTube or blogs because HA was and is changing too quickly. Especially at that time… if you stick with the real docs you will have much better luck as far as accuracy than using JimmytheTechGuys Blog. But as mentioned if you see an error we all have the ability to correct it…

I’m not trying to argue, just wanted to mention that the official docs have served me very well over these years… so I’d have to kindly disagree with you.

6 Likes
42

Sorry, I’m not trying to call you out, but you’ve brought up what I think is one of the larger underlying issues with the documentation:

If you’ve been using HA for a year or more, your documentation needs and view of the documentation is vastly different that a new user today that doesn’t yet understand much about Home Assistant.

When you already have an in-depth understanding of the system through experience, your documentation needs are for reference material.

However, a new user needs overview information, tutorials, and navigation that will help them understand all the moving parts and put them in context.

Someone who wants to improve the documentation needs to put themselves in the shoes of a new user and think about what does someone who doesn’t have HA expertise need to understand.

For example, imagine you just got Home Assistant installed and want to learn how to configure it, go to the top documentation page - https://www.home-assistant.io/docs/ You see this:

image
image1477×793 81.2 KB

Click Configuration. This brings you to https://www.home-assistant.io/docs/configuration/

image
image1049×546 49.2 KB

There is exactly one sentence that mentions the settings page, then we are off into the deep end about configuration.yaml that is going to be way over the head of a new user.

If you’ve been a round a long time, this may seem fine. But if you take a moment to think about that this may be one of the first documentation pages a new user visits after installation, and then think about what information should be there, this is the wrong content for this page.

A few of the things I would expect to be on https://www.home-assistant.io/docs/configuration/:

  • How to add devices to HA
    • Auto discovery and what do about devices that aren’t automatically discovered
    • (need to point to some place that describes what is an integration, device, entity, add-on, dashboard, card, …)
  • Overview of where things are configured in Home Assistant
    • Settings page
    • Dashboard configuration
    • Different types of configurable content
      • Home assistant core
      • Dashboard and card configuration
      • Browser and mobile app settings
      • Add-ons
      • Community/3rd party components

Maybe some of this exists in other places, but not under configuration where one is likely to look

As you mentioned, creators have been trying to fill that gap with videos and blogs. But as you mention they frequently go stale. Home Assistant has a rapid pace of innovation and evolution, so this is somewhat to be expected. Videos and tend to be write once, rarely updated, except through comments, and tend to clog up search results.

5 Likes
43

I mean I would expect the user to start with Installation:

Screen Shot 2022-10-11 at 12.36.15 PM
Screen Shot 2022-10-11 at 12.36.15 PM746×859 76.5 KB

I guess Configuration is kind of out of place in the previous screen, since it feels like these should be top level rather then buried under installation. But like most of what you just mentioned is in here. Takes you from true installation through onboarding and discovery to automation around your new stuff to a relevant example and then leads you to the community and more advanced topics if you want.

Merge this into the previous page and merge “Configuration” with “Advanced Configuration” and its pretty close, no?

44

So the Getting Started page you pointed out somewhat jumps from auto discovered integrations to automation. It does mention that you can add other integrations, though never really defines what an integration is or explains that you might need to add integrations such as Zigbee/Zwave/MQTT that gives you access to other networks/device domains which in turn might auto discover other devices or let you manually add them.

There is no configuration page. I wouldn’t really expect to find configuration info under onboarding.

Advanced configuration goes into configuration.yaml. It’s good to have that, though the example needs to be rethought, it shows editing through YAML the settings that are maintained in Settings->System->General. It should at least mention that these are normally maintained through the UI and this is just an example of overriding these the YAML way.

The Getting Started set of pages do have somewhat up to date content in tutorial form that matches the current experience of installing HA, HAOS, etc. However these pages are fairly brief and have a bunch of gaps. They are missing a lot of where to go for more information.

The pages under Documentation generally have older content and may be somewhat different from the current HA + HAOS experience. For example, look at the troubleshooting page https://www.home-assistant.io/docs/troubleshooting/. That page starts with talking about pip.

The point of all of this, is if you want to meaningfully improve the documentation some thought needs to be given to what a user needs to know and the perspective of relatively new users. The Getting Started pages are definitely a step in the right direction, but the documentation pages need work.

5 Likes
45

I am late to this conversation, but please lets not have a wiki. They too quickly get out of date.

3 Likes
46

I’ve been using Home Assistant for some time, and I almost never find usefull information in the docs, the examples doesn’t cover the subject or doesn’t exist, the language might be understandable for a true programmer, and being an algorithmic guy who’s actual programming is 30 years ago, it doesn’t make sense the way it’s written, the search engine is horrible, and the results give no meaning, the overview to the right is very bad, and helps only if you know where to look.
So spiffing up and reorganizing the docs is absolutely needed, and it’s a Herculean task. What I really don’t understand is the intense pushback from Nabu Casa people, it’s like they don’t WANT to see the need for this, I know it’s not sexy as making a new integration, and programmers are the worst people to document stuff, because terms are ‘inherently’ known, and thus not added for everybody else.

7 Likes
47

Who said that?

You’re getting pushback because all the people who contribute to the documentation understand it. It 100% makes sense to me. I know I’m not the best person to write or change the documentation because I don’t see ways to improve it. It’s likely that the whole Nabu Casa team thinks the same way.

So, why doesn’t someone here step up to the plate? I’m sure no one is going to shoot down the idea of making the documentation better for beginners.

48

it is a general known fact that:

  • devs don’t like to write documentation (they like to write code)
  • and when devs write documentation, it’s normally written as a coder (nerd language)
3 Likes
49

As a developer by trade I feel I have to word something here:
It’s incredibly hard to document your own code in a way that is 100 % understandable for someone with very little knowledge of the implementation. That is because you yourself have the best and entire knowledge of how the code you just wrote works.
This is the same reason it’s incredibly hard to test your own code - you know how it’s supposed to work and it’s pretty hard to come up with all the ways someone can fuck it up when you know the “happy flow” like the back of your hand.

That is why it’s very important that someone else than the developer tests the implementation and also why the persons most suitable to help improve the documentation when something is lacking is often the persons that didn’t understand the docs in the first place but then found a solution.

That said it doesn’t mean that every suggested change to the docs are good and should be implemented.

11 Likes
50

Plus one to that .

4 Likes
51

which is the case for all documentation sites or forums I know.

IMO the most efficient way to search sites is google search limited to particular address

2 Likes
52

It’s incredibly hard for anyone else to document your code when “you yourself have the best and entire knowledge of how the code you just wrote works”.

No one else knows what options, capabilities are in your code, how to enable / them etc.

I think it has to be a joint effort.

53

We already have the developers contributions right now. So…

54

I have made a few changes to the docs, it isn’t that hard, but you have to learn some markup. Pretty easy to learn.

1 Like
55

A suggestion: a documentation bug hunt (with a free month of Home Assistant Cloud for the top contributors? :smile: ), or some other form of gamification might encourage more users to increase and maintain documentation quality.

2 Likes
56

I hope it’s not asking too much, but would you be able to provide a straightforward step-by-step Intro for that? I mostly use github as a resource for looking up things, not so much for editing, and something like this could lower the threshold for people like me.
It wouldn’t address the bigger picture issues that were brought up throughout this threat, but it might at least get more people to fix things they stumble over :slight_smile:

57

A “how to edit the docs” doc page may be a pretty useful thing to put in the edit docs bottom bar. I think that is an actionable item that would improve experience.

Another mention in this thread is a last updated docs date shown on the page. I think that could be helpful as well.

An addition “was this helpful :+1::-1:” could help identify poorly done docs pages. The generated data would need to be surfaced, analyzed, and investigated to fully understand the issues but could be a useful way to identify poorly done docs pages.

58

Already done by someone else :slight_smile: Editing the Documentation and Creating a Pull Request on Github

But always happy to help if someone asks.

1 Like
59

You can click on the “edit this page” and it will take you to github, where you can see the entire page history. I agree though that the “last updated” right there on the page would be good.

1 Like
60

I highly appreciate the activity.

That said, it does not address the core of the problem. It matters not how good a single or collection of pages are, if the concepts, flow and structure of the overall documentation is troublesome.

There are too many concepts and structures that are interlinked in reality, yet almost impossible to decipher this from the documentation.

It is like describing the ingredients of a recipe in detail, but the steps of preparation, why, or several examples are not provided.

3 Likes