Index of Home Assistant documentation

Community Guides
#1

I’m several years into Home Assistant now and browse the forum most days, though this is my first post. A frustration which I think a lot of people share is with the documentation. We are urged to read the docs and they really are extensive and helpful, but they can also be very hard to navigate.

I have created an A-Z index which I hope people will find useful occasionally - particularly perhaps newcomers.

Nothing original here, just a collection of links, but a-z is second nature to everyone.

Updating

Currently being updated once a month (shortly after each new release). This includes a broken link check. Where possible, links are to pages rather than anchors within pages, so they should not be affected by changes to the content of the documentation.

There are bound to be omissions - the index includes a request form for missing items.

Note: the index does not include links to vendor- and device-specific implementations. Home Assistant have their own index here.

9 Likes
#2

Post the index in the official documentation (as opposed to where it’s now, on some external site). More users are likely to benefit from the index if it’s part of the documentation.

5 Likes
#3

Hi Jack, welcome to the forum!
Nice work, this can be useful and as Taras says: by placing it in the official documentation more people will benefit from it.

Have you seen this on the bottom of the documentation pages:

image
image1042×201 15.1 KB

#4

Figuring where to put it in the hierarchy of documentation should probably be done in collaboration with someone who is a regular doc contributor.

It is a great effort . However the devs may think it doesn’t match the look of the current docs.

Additionally it needs to auto generate, as the docs change regularly. The only thing worse than no index is an out of date index :slight_smile:

2 Likes
#5

Of course. Any suggestions?

This was deliberate to make it clear the page was unofficial. I’m revising it to get rid of all the buttons (which are a pain to update) but the colour scheme is staying the same.

Too right! :roll_eyes: I’m trying to make all the links to pages, rather than anchors within pages, on the assumption that the structure of the docs will change less often than the content. But it’s still a problem.

1 Like
#6

Well the doc github is GitHub - home-assistant/home-assistant.io: 📘 Home Assistant User documentation - maybe post an issue to gauge interest and tips.

#7

Do you have experience with Github? If so, why don’t you fork the documentation from the HA repo and change it like you want? The documentation is licensed to share and modify, as long as the copyright notices and the license remain intact, and it is not for commercial use, ie. you aren’t allowed to sell a new or reworked documentation.

But anything else, is totally ok. :slight_smile:

If you want to do it and don’t know how, I’m happy to help you setting up a fork in your Github repo and give you a little initial aid. :slight_smile:

EDIT:
On further thinking, that could be kind of a cool project to setup. You could fork the repo and rework the documentation on as many places you want (even if it’s “only” the index!). Afterwards you could host and even publish it, so people could choose between your and the original documentation.

And as the repos are connected via the fork, you could easily import every change in the original documentation to your fork and if necessary, change it to fit your design and ordering. Sounds nice, and doesn’t even cost a thing… :wink:

I’m thinking too far ahead :rofl: :rofl:

3 Likes
#8

Well, maybe just a bit… :tired_face:

At the moment I’m working with a sitemap, and as I said above, linking to pages rather than content. Apart from anything else, they’re not my docs to mess with.

This is obviously not sustainable though - and you’re right, it would be a cool project. Can I get back to you?

#9

Please do! :wink: :+1:

#10

Out of curiosity, I asked ChatGPT to do the job. It took about 10 seconds, and this was the result… :rofl:

#11

I honestly ask myself these days, why we are still on this planet? We finally found a way, to make even ourselves totally useless… :rofl: :rofl:

But all in all it is pretty impressive, what ChatGPT can do. :+1:

Nonetheless, I still believe, together we can beat the AI. :slight_smile:

#12

Indeed… But the only pages it listed were pre-September 2021, and half of those no longer exist. Skynet is not yet self-aware. :grinning_face_with_smiling_eyes: