[Feature Request] Table of Contents for Home Assistant Docs

Feature Requests
1

TL;DR. Please implement a usable Table of Contents to either augment or replace the Topics sidebar for the Home Assistant Documentation pages.

Over the past year of working with Home Assistant, I’ve encountered numerous situations where the solutions to my functionality issues came as a result of following a URL back to the Home Assistant Documentation pages. In most cases, I was lucky enough to encounter another community member who remembered exactly which page I needed to reference in order to fix my problem. Once the solution was implemented, I always found myself asking, “After all this time digging through the docs, why couldn’t I find this solution for myself?”

Now it’s great that this documentation exists but the way it is currently presented to the end user leaves much to be desired. The Topics sidebar is too basic. It doesn’t give readers any real sense of topic depth or complexity and therefore fails at its sole task - empowering readers with a concise list of topics and sub-topics at a glance.

Here is an example of a Table of Contents that accomplishes the aforementioned goal. It allows the user to see the top level subjects while also informing them of sub-topics that can subsequently be expanded upon (by clicking the arrow) should the user so desire. Simple and complex at the same time.

image

Had it not been for the amazing Home Assistant community and my stubborn refusal to be bested by a YAML file, I would likely have given up on Home Assistant long ago. Even now, after more than a year with Home Assistant, I feel navigating through the Documentation Pages is still a time consuming effort that could be so much easier. A true Table of Contents would go a long way to helping the rest of us get up to speed.

My apologies for the long post. Thank you for taking the time to read it through.

-Rob

2

There are a bunch of other fundamental things that don’t seem to have any explicit documentation that I’ve been able to discern. Stuff that seems like it’s idiomatic and we mindlessly replicate in our own YAML configurations without really understanding why.

For example, where would I find any documentation on what alias: is intended to do? Trying to search for it doesn’t yield anything useful. I can sort of see what it does, but I’m not sure what exactly the intended purpose is. Probably related to id: that likely would be used to specify the entity id for an automation when used there? But not entity_id: right?

As mentioned before, the documentation table of contents seems weirdly composed. There’s a link to “Entity Component Platform Options” under Advanced Configuration, that tells me about entity_namespace: which I’ve never seen used, or described how that might useful be employed; maybe within a package?

Having watched the comments go back and forth on a git pull request on some new feature, related to stylistic conventions and matters of taste on how something might be implemented… it really strikes me how really none of that happens when it related to the usefulness of documentation that’s committed for new components (or old). If the intent is to broaden the appeal to those that follow after early adopters (like hass.io seems to address), then documentation investments are going to be important.