Comments (9)
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.
Related Issues (20)
- The service call widget is not working HOT 1
- Notification to a group does not work as advertised HOT 5
- Ha
- building app minimal version fails HOT 4
- minimal builsd is failing HOT 4
- Add mention on the Sounds page that Android can't do this atm HOT 3
- Black Page opening Hacs and addons page After kast Ha update 2024.3.0 HOT 1
- Blank Pages and freeze + OSError: [Errno 24] Too many open files since the last update 2024.3.0 HOT 1
- Apple Watch: Direct to HA Communications over WiFi? HOT 1
- Clarify how to create an action in the Mac app
- Subtitle not shown in documentation HOT 2
- Debug help - logs after crash or crash report access?
- Favorite Entities never show on WearOS watch (Pixel watch) HOT 1
- Allow microphone usage for insecure connections HOT 2
- Back & Hamburger Button on "Error while loading page lovelace." screen malfunction HOT 3
- Complications do not update on TTW (tilt to wake) HOT 1
- Dead Doc Link - Wear OS Setting - Android App
- Searches for Home Assistant Server HOT 3
- Does the home assitant android app have requirements for the android version HOT 5
- Complication does not auto update HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from companion.home-assistant.