Site Structure

[SeanPM5]

Have been thinking of altering the site structure to make things easier to find and navigate. Proposing a new structure here which I think would be a massive improvement personally.

Current way has things more siloed off and in kind of weird, hard to discover areas imo. Theming is not really an integration, and I don't feel like Sensors are an integration either... And then in the Notifications section for example it feels like there's a sort of arbitrary differentiation between basic and advanced. And depending on which section you clicked first you can't really see the other pages easily, Location section for example has no sidebar at all.

Proposed Structure & Sidebar:

• Getting Started
  • Beginners Guide
  • Migrating from Old App
• Core Features
  • Location
  • Sensors
  • Actions
• Notifications
  • Basic Notifications
  • Sounds
  • Attachments
  • Dynamic Attachments (renamed from Dynamic Content)
  • Actionable Notifications
  • Critical Alerts
  • Technical Details (Merge "Architecture" & "Privacy, rate limiting and security" page)
• Integrations
  • Apple Watch
  • Actions
  • Complications
  • NFC & Universal Links
  • Siri Shortcuts
  • URL Handler
  • X-Callback-URL
• Other
  • Theming
  • Haptics
  • App Events
• Troubleshooting
  • Setup and Connectivity
  • Integration Troubleshooting
  • Resetting app
  • Get more Help (Discord, Forum, etc)

I think those are broken out into clearly distinct categories, and it solves the issues mentioned above, makes navigation easier, makes it easy to discover the various features of the app. Probably only a handful of page redirects would be needed.

Header would stay mostly the same I think, except "Misc" & "Help" links get merged to one "Troubleshooting" link.

[TomBrien]

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.

[SeanPM5]

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.

[robbiet480]

@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 8dd2d832b2d305386e49d400c9e4944e19615933

[robbiet480]

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!

[SeanPM5]

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.

[TomBrien]

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?

[robbiet480]

feel free to merge on your own