docs: Add troubleshooting section (#549)

Author: mykola-mokhnach

README.md

@@ -1173,6 +1173,62 @@ The history of W3C support in Chromedriver is available for reading at
 [downloads section](https://sites.google.com/a/chromium.org/chromedriver/downloads).
 
 
+## Troubleshooting
+
+### Activity Startup
+
+If you experince issues with application activities being not found or not starting then consider checking [How To Troubleshoot Activities Startup](docs/activity-startup.md) article.
+
+### Poor Elements Interaction Performance
+
+If you observe automated tests need at least 10 seconds or more to locate/interact with a single element then consider changing the default value for [waitForIdleTimeout setting](#settings-api). By default, UiAutomator framework (and all other Accessiblity-based frameworks) always waits for the accessibility event stream to become idle before interacting with it (the default timeout there is 10000ms). This is needed to make sure all animations/transitions are finished before you, for example, interact with an element by clicking it. In case the application under test constantly runs some background animations or hogs the accessibility event stream in some other way these waits may significatly slow down the automation flow.
+
+Setting the value of `waitForIdleTimeout` to zero `0` ms should completely disable any waits, and enforce interactions to happen immediately ignoring the accessibility event stream state. The downside of that would be that all interactions are never going to be delayed, so clicks and other actions might happen at wrong places of the application UI. That is why is it important to check the app under test first and fix its source to get rid of activities hogging the event loop. Sometimes it makes sence to disable animations completely for the app build under test, which could speed up your flows significantly in some situations.
+
+> **Warning**
+> `waitForIdleTimeout` is a setting, not a capability.
+
+### Session Startup Issues
+
+Sometimes various legacy driver parts might be cached on the device under test (like settings.apk), which would prevent a new/upgraded driver version from starting a session. Run
+
+```bash
+appium driver run uiautomator2 reset
+```
+
+in order to cleanup the cached UIA2 driver binaries from all connected devices on the current machine.
+
+### Element(s) Cannot be Found
+
+All element location strategies in UIA2 driver work similarly under the hood except of the xpath one.
+If some element is not found, but you see/assume it is present in the page source then make sure no race condition
+happens. Add a timer and wait for a couple of seconds before giving up on the element location. In case the lookup
+still fails after the timeout and your non-xpath locator is used then, most likely, it contains a typo, or the
+destination element is not present. There is not much that could be done in UIA2 to change/influence that, since it passes such lookup calls directly to Google's UiAutomator framework.
+
+In case of xpath locators you could also try to change values of the following settings:
+
+1. [allowInvisibleElements](#settings-api)
+2. [ignoreUnimportantViews](#settings-api)
+3. [enableMultiWindows](#settings-api)
+
+By default, the first setting is set to `false`, which hides
+elements that are not visible from the the page source and from the xpath location. Changing the setting value
+to `true` would add such invisible elements to the page source and make them locatable.
+
+The second one is enabled by default (e.g. `true`). By disabling it the page source could receive more elements
+that are normally hidden, because of their unimportance.
+
+The third setting being set to `true` extends the page source by adding the actual content of other windows that are currently present on the device's screen. For example, the on-screen keyboard in Android is not a part of the current app hierarchy, but rather belongs to a separate window.
+
+> **Warning**
+> Default values for settings above have been selected to optimize xpath lookup and page source generation performance.
+> Having these settings always different from their default values may sometimes significantly (especially in case of huge accessbility hierarchies) reduce xpath lookup and page source generation speed.
+
+> **Warning**
+> All items above are settings, not capabilities.
+
+
 ## Usage Examples
 
 ```python