Generalizing docs for Android and iOS about companion.home-assistant HOT 9 CLOSED

When #152 is merged, the syntax to include the Android and iOS icons will change slightly to become

![iOS](/assets/apple.svg) iOS instructions.

![android](/assets/android.svg) Android instructions.

This is changed from assets/... to /assets/...

I've updated the comment above

from companion.home-assistant.

I agree that these need generalising. I don't run android so it's hard for me to comment on the exact differences however, I have been increasingly trying to keep things generic. There will always be steps that are platform dependent but the main bulk of how the apps work is, to the best of my understanding, as generic as possible. Here are my thoughts of a sensible way forward:

• One way of handling this might be to use language specific code blocks to handle the difference. I don't think there is a way to set the default based on the user's platform sadly.
• Another way would be to cut a different version of the docs for Android and iOS but you can only have one landing page. Can CloudFlare handle platform dependent redirects? This is a possible work around if we did go down that route
• There is of course the two-site idea but that will likely result in useful information not being shared between the two apps
• Other better ideas I haven't thought of.

I think I favour the first option. It is possible that we can write the docs in a completely generalised way but I see this relying more on the user's knowledge of their mobile OS and from my experience of the 1.5 - > 2019.1 migration the hand holding in the current docs is useful.

from companion.home-assistant.

I think we're already well on the way. Judging from the support fallout from upgrading iOS app to 2019.1 we are looking at (currently) app specific issues around usability and OS specifics (think pull-to-refresh and iOS permission stuff) which should be covered in platform docs (ios & android) and then what is pretty agnostic around helping people set up remote access to their home networks properly. This generic section is, I believe, pretty well covered and only needs moving around.

It would make life a lot easier if things like setting up actions could be configured in HA UI and imported to the apps, same for actionable notification categories (necessary on iOS but should be possible to do just in HA like HTML5 notify).

from companion.home-assistant.

I don't have first-hand experience with the Android app yet, I need to buy a budget/prepaid Android phone sometime soon to play around with this stuff.

My understanding is that things like initial setup, location, notifications, and troubleshooting will be extremely similar across both platforms once the Android app gets a bit further along. So if there's gonna be feature parity, it'd make sense to share those pages.

The existing pages could have some minor tweaks to generalize the instructions a little more. Whenever screenshots are displayed on these shared pages, I think we should make an effort to show Android and iOS screenshots side-by-side.

When instructions diverge between platforms on these shared pages, there's numerous options for how to deal with that:

• The language specific code blocks (aka tabs) that Tom mentioned above
• Could maybe display like a 24px Android or iOS logo icon at the start of certain paragraphs to indicate those instructions are only for that platform.
• Or even just bold text. Something like "Note for Android users: blah blah"
• Some features like Critical notifications are subpages already, these could simply have their titles updated to be more descriptive such as "iOS Critical notifications" or "Critical notifications (iOS only)"

Aside from that, I propose that we simplify the site structure a little bit by merging the "Core Features" page and "Integrations" page into a single page titled just "Features."

This would bring the header navigation from 5 links down to 4, and it would allow the user to see every nav option without having to scroll. Right now you have to horizontally scroll in order to see the "Troubleshooting" page when you're on a mobile device.

Everything on this "Features" page would be organized into one of three groups: Core, iOS, Android.

• Core - features that are common/shared between both apps. Location, Sensors, Theming, etc.
• iOS - platform specific features like Apple Watch, Shortcuts, Actions, App Events, etc.
• Android - platform specific features like Google Fit, Google Wear etc.

I feel this would be a very clean way of handling this.

from companion.home-assistant.

So where do we stand with this issue? I feel that we should try to get something going before the Android app gets more features and it becomes difficult to remember it all. Plus once we get a standard in place we can start requiring docs updates from future PR's as well.

I personally like generalizing things a bit more so we have Core followed by OS specific bits on shared features like location and basic notifications. I think the icon approach would be a better fit than tabs since tabs inside a site can be easy to miss but those icons are easy to distinguish, especially android. Also pages that are OS specific should be properly labeled with the same icons. Not sure if we need to fully separate them. I imagine most households would be a mixture of devices so the easier the navigation between the 2 OS's that we support the better. More than likely it will be the same person troubleshooting or setting up the app :)

from companion.home-assistant.

These are good points on the icon front lets go down that route. I've added Apple and Android icons which can be included with

![iOS](/assets/apple.svg) iOS instructions.

![android](/assets/android.svg) Android instructions.

There are some rules added to custom.css to ensure that these are styled inline rather than as a block. This only applies to those two files.

from companion.home-assistant.

So I started to take a crack at this here: https://github.com/dshokouhi/companion.home-assistant/blob/patch-1/docs/notifications/basic.md

Android doesn't support a lot yet but when I started to modify the section related to notify.group I realized that if we really want things to work properly especially for households that have both Android and iOS devices it would be best if the service data was kept as close as possible. For example right now only message and title can be properly grouped together as the payload is the same. If a user wants to send an image or actionable notification they will need to do so separately and may need to create additional groups to circumvent this.

I think this brings up a good point as well because the closer the configuration is to each other the easier these docs will be to maintain when it comes to features. So my thoughts for now were to go section by section and show the iOS and/or Android icon for when something is supported or not by the platform.

Updating a section like actionable notifications will be interesting because most of what is there really only applies to iOS. Android only has some differences when it comes to the service data and processing the event triggers.

from companion.home-assistant.

Ok I have gone through the remaining pages and think I have added in as much as we have on Android ATM. Shall we close this issue or keep it open in case other areas were missed?

from companion.home-assistant.

Gonna close some issues here for things that were implemented, this one was figured out and done very successfully, good job guys :)

from companion.home-assistant.