Refactor and clean up the migration guide.

UPDATING.md

@@ -7,23 +7,25 @@ We have made **breaking changes** in the version 1.2 release of this SDK.
 In this guide we aim to highlight the main differences you will encounter when migrating your code from the interfaces we were offering prior to the version 1.2.0 release.
 
 These include:
- - Deprecating Python 3.4, 3.5 and 3.6
- - Introduction of Asynchronous way of using the SDK
 
-### Using the SDK API in synchronous way
+ - Deprecation of support for Python versions 3.4, 3.5 and 3.6
+ - New, asynchronous API
 
-This way using it is still possible. In order to use SDK in synchronous way please use the <= 1.1.0 version of this SDK.
+### Deprecation of Python 3.4, 3.5 and 3.6
 
-### Deprecating Python 3.4, 3.5 and 3.6
+The minimum version of Python has increased to 3.7.
+You may need to upgrade your environment in order to use this newer version of this SDK.
+To see which versions of Python we test the SDK against, please look at our
+[GitHub workflows](.github/workflows).
 
-The minimum version of Python has increased from 3.7. At this time we test against 3.7, 3.8, 3.9 and 3.10. Please upgrade your environment in order to use the 1.2.x version.
+### Asynchronous API
 
+The 1.2.0 version introduces a breaking change, which changes the way of interacting with the SDK from synchronous to asynchronous, using [the `asyncio` foundational library](https://docs.python.org/3.7/library/asyncio.html) to provide support for `async`/`await` syntax.
+Because of this breaking change, every call that interacts with the Ably REST API must be refactored to this asynchronous way.
 
-### Introduction of Asynchronous way of using the SDK
+#### Publishing Messages
 
-The 1.2.x version introduces breaking change, which aims to change way of interacting with the SDK from Synchronous way to Asynchronous. Because of that every call that interacts with the Ably Rest API must be done in asynchronous way.
-
-#### Synchronous way of using the sdk with publishing sample message
+This old style, synchronous example:
 
 ```python
 from ably import AblyRest
@@ -33,12 +35,11 @@ def main():
     channel = ably.channels.get("channel_name")
     channel.publish('event', 'message')
 
-
 if __name__ == "__main__":
     main()
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 import asyncio
@@ -49,12 +50,13 @@ async def main():
         channel = ably.channels.get("channel_name")
         await channel.publish('event', 'message')
 
-
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-#### Synchronous way of querying the history
+#### Querying History
+
+This old style, synchronous example:
 
 ```python
 message_page = channel.history() # Returns a PaginatedResult
@@ -63,7 +65,7 @@ message_page.has_next() # => True, indicates there is another page
 message_page.next().items # List with messages from the second page
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 message_page = await channel.history() # Returns a PaginatedResult
@@ -73,47 +75,53 @@ next_page = await message_page.next() # Returns a next page
 next_page.items # List with messages from the second page
 ```
 
-#### Synchronous way of querying presence members on a channel
+#### Querying Presence Members on a Channel
+
+This old style, synchronous example:
 
 ```python
 members_page = channel.presence.get() # Returns a PaginatedResult
 members_page.items
 members_page.items[0].client_id # client_id of first member present
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 members_page = await channel.presence.get() # Returns a PaginatedResult
 members_page.items
 members_page.items[0].client_id # client_id of first member present
 ```
 
-#### Synchronous way of querying the presence of history
+#### Querying Channel Presence History
+
+This old style, synchronous example:
 
 ```python
 presence_page = channel.presence.history() # Returns a PaginatedResult
 presence_page.items
 presence_page.items[0].client_id # client_id of first member
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 presence_page = await channel.presence.history() # Returns a PaginatedResult
 presence_page.items
 presence_page.items[0].client_id # client_id of first member
 ```
 
-#### Synchronous way of generating a token
+#### Generating a Token
+
+This old style, synchronous example:
 
 ```python
 token_details = client.auth.request_token()
 token_details.token # => "xVLyHw.CLchevH3hF....MDh9ZC_Q"
 new_client = AblyRest(token=token_details)
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 token_details = await client.auth.request_token()
@@ -122,7 +130,9 @@ new_client = AblyRest(token=token_details)
 await new_client.close()
 ```
 
-#### Synchronous way of generating a TokenRequest
+#### Generating a TokenRequest
+
+This old style, synchronous example:
 
 ```python
 token_request = client.auth.create_token_request(
@@ -136,7 +146,7 @@ token_request = client.auth.create_token_request(
 new_client = AblyRest(token=token_request)
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 token_request = await client.auth.create_token_request(
@@ -151,30 +161,34 @@ new_client = AblyRest(token=token_request)
 await new_client.close()
 ```
 
-#### Synchronous way of fetching your application's stats
+#### Fetching Application Statistics
+
+This old style, synchronous example:
 
 ```python
 stats = client.stats() # Returns a PaginatedResult
 stats.items
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 stats = await client.stats() # Returns a PaginatedResult
 stats.items
 await client.close()
 ```
 
-#### Synchronous way of fetching the Ably service time
+#### Fetching the Ably Service Time
+
+This old style, synchronous example:
 
 ```python
 client.time()
 ```
 
-#### Asynchronous way
+Must now be replaced with this new style, asynchronous form:
 
 ```python
 await client.time()
 await client.close()
-```
+```