Share your CONCRETE struggles with the documentation!

Social
1

Hey everyone, while a lot of people were sharing their overall highlevel issues with the HA documentation in WTH is there no consistent documentation concept?, I’m considering digging into the topic a bit more. I have my own examples of pages where I ran into issues, but I’d like to hear yours as well. What were the documentation pages which you gave up on because they didnt answer your questions? Which were the ones where you instead googled for other resources (and which resources did do the trick for you in the end)? Which pages turned out just plain wrong content-wise? Or which pages were individually okay, but would have profited from being closer linked and therefore easier to find?

Please be as concrete as possible :slight_smile:

Thanks for sharing!

1 Like
2

I had an issue opened a while ago for the search function duplicating page results, but the stalebot closed it.

Aside from that, search in general is lackluster and I rarely find what I’m looking for using it.

I also tend to come across yaml examples that don’t necessarily work by themselves. I think they’re usually meant to be nested under another section of yaml, but without having the full example provided it’s sometimes not clear how much the example yaml should be indented. Or, maybe I just don’t understand yaml enough.

Even though I know the difference, I still find myself going to the wrong “template” document almost every time - there’s “Template” for the integration, but there’s also a page for templating.

I also find the table of contents along the right side doesn’t always expose all the pages that are actually in the documentation. I’ve come across a handful of useful documentation pages that are linked directly from the forums, but that I’ve never seen by just browsing around on the documentation site.

1 Like
3

At a quick glance

Documentation does not start with Installation, Configuration, MQTT, Dashboards, Android and iOS.

It starts with concepts how HASS works. Lot of the information from the Developers site could be copied, like Architecture, front-end, back-end.

Structure and naming convention @petro pointed to the Glossary. The glossary needs to be updated.

Add all the key words used in documentations to the glossary (e.g. intent, helper, area, tags, dashboard)

Full examples, examples, and did I mention examples? There needs to be complete examples both for the UI, and YAML items. There are some pages that have excellent examples, some lack it.

Clean up what goes and does not go into configuration.yaml.

Update screenshots to the latest major version where possible in default/vanilla mode.

In examples and how to get to something provide full set of bread-crumbs. It is not enough to write “click add integration”, it must explain how to get to such screen, each and every single time from the front “home” page.

Explain what each default menu option has under it at high level then take to a that page. (Overview, Energy, Map, Logbook, History, etc.)

1 Like
4

Got some concrete examples to link to? Thanks :slight_smile:

5

Sure.
without Events - Home Assistant
with Script Syntax - Home Assistant

2 Likes
6

I’m not sure what examples you’d need for events… What examples are you specifically looking for there? That’s describing typical information you’d see in an event.

Using events is only relevant to triggers, service calls, and trigger templates. All which cover events with examples.

7

From Entity | Home Assistant Developer Docs

The friendly_name state attribute is generated by combining then entity name with the device name as follows:

‘friendly name is generated’? Generated by who and where? Should I generate the name somewhere in my code or is it this ‘friendly name’ generated automatically by the framework code according to the templates below?

  • The entity is not a member of a device: friendly_name = entity.name
  • The entity is a member of a device and entity.name is not None: friendly_name = f"{device.name} {entity.name}"
  • The entity is a member of a device and entity.name is None: friendly_name = f"{device.name}"

Suggestion: “Generate friendly_name according to the following rules in ___.”
or “Hass framework generates friendly_name according to following rules:”

8

That’s a development doc. Doesn’t really fit in this context.

As to who and where, it’s by the integration when it’s installed.

As for a concrete example I’d have to suggest the mqtt sensor format examples, they seem to be tripping alot of people up.

9

TL;DR: Bluetooth based integrations do not explicitly state what kind of bluetooth support they require, meaning you need to go digging for it / find out after you’ve spent time and money on hardware and configuration that they require something different.

Example: Oral-B Oral-B - Home Assistant

Explanation:
I was looking to maybe use the new Oral-B integration (and don’t have anything in terms of bluetooth set up yet), but it doesn’t clearly tell me what kind of Bluetooth is supported, just that:
“The Oral-B integration will automatically discover devices once the Bluetooth integration is enabled and functional.”

This sort of hints at the fact that it might be based on passive bluetooth advertisement scanning? But now I’ll have to go dig in git in order to figure this out because i can’t be sure…

Clicking through to that bluetooth integration links just provides me with the 4+ options of getting bluetooth to work with varying levels of functionality/support stating things like:
“Many integrations require active scanning and may not function when scanning is passive.”

… Right, makes sense. Then why isn’t this clearly stated and/or labeled on the page of my bluetooth based integration of interest: Oral-B?

I am left questioning: can I use an ESPHome based bluetooth relay, or do i really need an adapter plugged into my HASS box directly? Or are there any non-local setup variants that are not Bluetooth relay based that will work for this integration? My HASS box is out of reach of my bathroom so a local adapter won’t fit my scenario…

1 Like
10

TLDR: having an easier way for those of us who want to help in the way we can (clarifying/improving documentation) would be fantastic.

I’m not a programmer and have never used GitHub for anything other than reading documentation and downloading stuff. But I’m also definitely not illiterate with tech.

I recently tried to figure out how to submit changes to clarify some documentation, and for the life of me I couldn’t figure out what the hell I was doing…was I forking the whole project? Or just the documentation? I dunno…ok let’s see what happens. Ok…now I have a fork…How do I push my fork to the main author to implement the change? Beats the heck out of me. I wound up giving up. (Granted I was also on mobile, it’s possible I could have sorted it on a real computer…).
.

Edit: I know that’s not quite what you were asking for, but I suspect making fixing docs easier might get more people involved in the process.

3 Likes
11

Recently I struggled with Utility meter. The Documentation of this (via Docs → Integration) is outdated at least twice. It is now in Helpers and is configured in the UI, which is great. So at least there shoul be an hint of this in the documentatikon. Also there is no explanation of the difference / the dirfferent use cases of utility_meter.reset and utility_meter.calibrate. The example in the documantation is way too complicated for beginners and hard to follow. There are things like tariffs, but this is not explained, merel not even mentioned. So I almost gave up to create a utility meter without cycling but amnual reset for my gas tank, but I found help in a 3rd-party discord.

1 Like
12

As I wrote before:

I appreciate the attempt to fix things.

The first and foremost CONCRETE struggle for me is the structure of the documentation. In my opinion, the nuanced pieces (several listed here) are the manifestation, the symptoms of the underlying problem.

… that even a relatively well-written and comprehensive set of reference docs is not “the documentation.” This is a popular point of discussion, even a kind of programmer machismo – “Just give me the API docs and I’m good to go!” Yeah, well, maybe. If you already know what you’re doing, API docs are where you’ll spend all your time. But if you just walked up cold to a new technology, good luck trying to suss it all out from the descriptions of the classes and members. And that’s if you’re a smart guy, never mind a guy like me who is a bit slow on the uptake. - [Mike Pope](No docs == no product - mike's web log)

Home Assistant is now crossed the borders of tech geeks realm. There are more and more users who are not technologists yet enjoy HA and want to take even more advantage of it.

1 Like