docs: cleanup migration doc

website/docs/MigrationV2.md

@@ -3,75 +3,72 @@ id: migration-v2
 title: Migration to 2.0
 ---
 
-This guides describes major steps involved in migrating your testing code from using React Native Testing Library version `1.x` to version `2.0`.
+This guide describes steps necessary to migrate from React Native Testing Library `v1.x` to `v2.0`.
 
 ## Dropping Node 8
 
-Node 8 reached its EOL more than 5 months ago, so it's about time to target the library to Node 10. If you used lower version, you'll have to upgrade to v10, but we suggest using the latest LTS version.
+Node 8 reached its EOL more than 5 months ago, so it's about time to target the library to Node 10. If you used lower version, you'll have to upgrade to v10, but we recommend using the latest LTS version.
 
 ## Auto Cleanup
 
-`cleanup()` function is now called automatically after every test, if your testing framework supports `afterEach` hook (like Jest, mocha, and Jasmine).
+`cleanup()` function is now called automatically after every test if your testing framework supports `afterEach` hook (like Jest, Mocha, and Jasmine).
 
-You should be able to safely remove all `afterEach(cleanup)` calls in your code.
+You should be able to remove all `afterEach(cleanup)` calls in your code.
 
-This change might break your code, if you tests are not isolated, i.e. you call `render` outside `test` block. Generally, you should [keep your tests isolated](https://kentcdodds.com/blog/test-isolation-with-react), but if you can't or don't want to do this right away you can prevent this behavior using any of the following ways:
+This change might break your code, if you tests are not isolated, i.e. you call `render` outside `test` block. Generally, you should [keep your tests isolated](https://kentcdodds.com/blog/test-isolation-with-react). But if you can't or don't want to do this right away you can prevent this behavior using any of the following ways:
 
-1. by importing `'react-native-testing-library/pure'` instead of `'react-native-testing-library'`
+- by importing `'react-native-testing-library/pure'` instead of `'react-native-testing-library'`
+- by importing `'react-native-testing-library/dont-cleanup-after-each'` before importing `'react-native-testing-library'`. You can do it in a global way by using Jest's `setupFiles` like this:
 
-2. by importing `'react-native-testing-library/dont-cleanup-after-each'` before importing `'react-native-testing-library'`. You can do it in a global way by using Jest's `setupFiles` like this:
-
-```js
-{
-  setupFiles: ['react-native-testing-library/dont-cleanup-after-each'];
-}
-```
+  ```json
+  {
+    "setupFiles": ["react-native-testing-library/dont-cleanup-after-each"];
+  }
+  ```
 
-3. by setting `RTNL_SKIP_AUTO_CLEANUP` env variable to `true`. You can do this with `cross-evn` like this:
+- by setting `RTNL_SKIP_AUTO_CLEANUP` env variable to `true`. You can do this with `cross-evn` like this:
 
-```sh
-cross-env RNTL_SKIP_AUTO_CLEANUP=true jest
-```
+  ```sh
+  cross-env RNTL_SKIP_AUTO_CLEANUP=true jest
+  ```
 
 ## WaitFor API changes
 
-`waitForElement` function has been renamed to `waitFor` for consistency with React Testing Library. Additionally the signature has slightly changed from:
+We renamed `waitForElement` function to `waitFor` for consistency with React Testing Library. Additionally, the signature has slightly changed from:
 
 ```jsx
 export default function waitForElement<T>(
   expectation: () => T,
   timeout?: number,
   interval?: number
- : Promise<T> {
+): Promise<T> {}
 ```
 
 to:
 
 ```jsx
 export default function waitFor<T>(
   expectation: () => T,
-  {
+  options: {
     timeout?: number,
-    interval?: number
+    interval?: number,
   }
-): Promise<T> {
+): Promise<T> {}
 ```
 
 Both changes should improve code readibility.
 
-:::note
-Please note that in many cases `waitFor` call can be replaced by proper use of `findBy` asynchonous queries resulting in more streamlined test code.
+:::tip
+You can usually avoid `waitFor` by a proper use of `findBy` asynchronous queries. It will result in more streamlined testing experience.
 :::
 
 ## Removed global `debug` function
 
-Global `debug()` function has been removed in favor of `debug()` method returned from `render()` function.
+The `debug()` method returned from `render()` function is all you need. We removed the global export to avoid confusion.
 
 ## Removed global `shallow` function
 
-Global `shallow()` functions which has been previously deprecated has been removed.
-
-Shallow rendering React component is usually not a good idea, so we decided to remove the API. However, if you find it useful or need to support legacy tests, feel free to implement it yourself. Here's a sample implementation:
+Shallow rendering React component is usually not a good idea, so we decided to remove the API. But, if you find it useful or need to support legacy tests, feel free to use this implementation:
 
 ```js
 import ShallowRenderer from 'react-test-renderer/shallow';
@@ -93,7 +90,7 @@ Following query functions have been removed after being deprecated for more than
 - `queryByName`
 - `queryAllByName`
 
-The `*ByType` and `*ByProps` queries has been prefixed with `UNSAFE_`. You can safely rename them using global search/replace in your project:
+The `*ByType` and `*ByProps` queries has been prefixed with `UNSAFE_`. You can rename them using global search/replace in your project:
 
 - `getByType` -> `UNSAFE_getByType`
 - `getAllByType` -> `UNSAFE_getAllByType`
@@ -104,21 +101,25 @@ The `*ByType` and `*ByProps` queries has been prefixed with `UNSAFE_`. You can s
 - `queryByProps` -> `UNSAFE_queryByProps`
 - `queryAllByProps` -> `UNSAFE_queryAllByProps`
 
-## Some `byTestId` queries behavior changes
+## Some `ByTestId` queries behavior changes
+
+In version `1.x` the `getByTestId` and `queryByTestId` queries could return non-native tinstances. This was a serious bug. Other query functions like `getAllByTestId`, `queryAllByTestId`, `findByTestId` and `findAllByTestId` didn't have this issue. These correctly returned only native components instances (e.g. `View`, `Text`, etc) that got the `testID`.
 
-In version `1.x` `getByTestId` and `queryByTestId` could return non-native elements in tests. This was in contrast with other query functions: `getAllByTestId`, `queryAllByTestId`, `findByTestId` and `findAllByTestId` which returned only elements that would be rendered to native components (e.g. `View`, `Text`, etc).
+In v2 we fixed this inconsistency, which may result in failing tests, if you relied on this behavior. There are few ways to handle these failures:
 
-If you relied on setting `testID` for your custom components, you should probably set them on the root element of the returned JSX.
+- pass the `testID` prop down so it can reach a native component, like `View` or `Text`
+- replace `testID` with proper `accessibilityHint` or `accessibilityLabel` if it benefits the user
+- use safe queries like `*ByText` or `*ByA11yHint`
 
 :::caution
-In general, you should avoid `byTestId` queries when possible and rather use queries that check things that can been seen by the user (e.g. `byText`, `byPlaceholder`, etc) or accessability queries (e.g. `byA11yHint`, `byA11yLabel`, etc).
+In general, you should avoid `*byTestId` queries when possible. Use queries that check things that the user can interact with. Like `*ByText` or `*ByPlaceholder` or accessibility queries (e.g. `*ByA11yHint`, `*ByA11yLabel`).
 :::
 
 ## Deprecated `flushMicrotasksQueue`
 
-We have deprecated `flushMicrotasksQueue` and plan to remove it in the next major version, as currently there are better alternatives available for helping you write async tests: `findBy` async queries and `waitFor` helper.
+We have deprecated `flushMicrotasksQueue` and plan to remove it in the next major. We have better alternatives available for helping you write async tests – `findBy` async queries and `waitFor` helper.
 
-If you can't or don't want to migrate your tests, you can get rid of the deprecation warning by copy-pasting function's implementation into your project:
+If you can't or don't want to migrate your tests, don't worry. You can use the same implementation we have today:
 
 ```js
 function flushMicrotasksQueue() {