Site Structure about companion.home-assistant HOT 7 CLOSED

So I'm working through the Watch docs and convinced myself that watch should be it's own top-level category (it is an app in its own and there's a fair bit to go in there under complications). In doing so I ran into the issue Robbie had with the Misc page and versioning (even stumbled across the Git Hub issue). I think those changes may be very hard to implement as the HeaderLinks are not versioned and have to be consistent across all versions. E.g. I've had to create a Watch App page in 1.0.0 saying there isn't a watch app for 1.0.0. I'm not sure about burying things like location and notifications as sub items.

from companion.home-assistant.

Location and Notifications would not be buried, since they'd still be featured in the header exactly like they are now, and both are also located near the very top of sidebar too. I would argue this actually gives them much more visibility because now every page would be visible in the sidebar at all times.

Here is a very quick mockup of what I'm proposing, side by side with current version (click for bigger size):

Note: sidebar in mockup is not fully complete since it's a quick mockup just to provide visual example of how this would look. (Also see Home Assistant dev docs for a working example of a sidebar like this in action - I find it very easy to navigate those docs).

But you can see in the current version (front), the Location page has no sidebar at all for example. If someone gets to this page via Google, they wouldn't see everything this app has to offer unless they were curious enough to click around in the header. This same issue applies to other pages, everything is siloed off and isolated.

But in the mockup version, user would see the sidebar and be like "Wow, I didn't know the app could do X and Y and Z."

Benefits of this:

• Everything is literally one click away.
• You don't have to guess where something is, it's shown to you in neatly organized sections.
• Greatly increases visibility of app feature set.
• Better for search engine optimization since everything is cross-linked and passing page rank or whatever.

I don't know about the technical aspect of this in terms of versioning etc, so that's why I floated the idea to you guys first. I personally don't see any drawbacks from this approach besides the one-time annoyance of changing the structure. And it's a lot easier to figure this stuff out now than later.

It may seem like a major change but I think the work required wouldn't be too bad.

Things that would be moved / renamed:

1. actions.md, sensors.md, theming.md get moved out of "integrations" folder into a new "app" folder. app-events.md would be moved out of "misc" to this "app" folder. The haptics.md page that I am gonna start working on soon would go here as well. The "app" folder is basically a catch all category that any file could fit into.
2. "misc" folder gets renamed "troubleshooting" and the folder contents stay largely the same.
3. Header stays almost exactly the same except for two links ("Misc" and "Help") being merged into a single "Troubleshooting" link. So it brings the header down from 6 links to 5, simplifying it a bit.

from companion.home-assistant.

@TomBrien You can freely change the header links, they just have to continue linking to files that existed in 1.0. If the file didn't exist in 1.0, just go back in time and fix it like I did at 8dd2d83

from companion.home-assistant.

As I told @SeanPM5 just now on Discord, in my mind, @SeanPM5 and @TomBrien are 100% owners of this now, so if you want to make these massive changes you can seek my input but its not required. Having said that, this all looks fantastic and has my full support!

from companion.home-assistant.

Another benefit I am noticing just now about this structure, is that it's mostly platform agnostic except for the Integrations section. So theoretically, when the Android app becomes a thing it could possibly share these same docs, and we would simply segment the Integrations section into sub-sections (Integrations/iOS and Integrations/Android).

There would still be certain platform specific sections on some pages I guess, like the "importing iOS default sounds" on the Sounds page, but I think most people wouldn't mind at all... Anyway, this is not something to worry about at all right now obviously, just kind of thinking out loud here. Main point of this comment is that the proposed structure seems future proof to me.

from companion.home-assistant.

Ok I'm sold! Happy to implement this during today. @robbiet480 on that note. Do you still want oversight of merging or shall we deload you slightly (I'm guessing by only the smallest amount) and agree a system where I check Sean's PRs and vice versa then merge?

from companion.home-assistant.

feel free to merge on your own

from companion.home-assistant.