docs: update v7.0.0 migration

MIGRATION_v7.0.0.md

@@ -4,13 +4,19 @@ This document covers all breaking changes introduced with v7.0.0.
 
 If you migrate from v6.X.X to v7.X.X (or above), you will have to handle the following points in your codebase.
 
-## Everything flagged with an `Obsolete` annotation will be removed
+### Everything flagged with an 'Obsolete' annotation has been removed
 
-### Synchronous methods
+When upgrading to a newer release, you may have noticed a warning indicating you're using an obsolete method.
+Indeed, we flagged these changes with an `Obsolete` tag.
 
-So far, a lot of features are available with both synchronous/asynchronous implementation.
-In [v7.0.0](https://github.com/Vonage/vonage-dotnet-sdk/releases/tag/v7.0.0), all synchronous methods will be removed.
-If you still require to call a Vonage API in a synchronous context, you will have to call the asynchronous version with
+Please note that there's always a substitute when we decommission something.
+
+#### Synchronous methods
+
+So far, many features are available with both synchronous/asynchronous implementation.
+All synchronous methods have been removed in [v7.0.0](https://github.com/Vonage/vonage-dotnet-sdk/releases/tag/v7.0.0).
+If you are still requires to call a Vonage API in a synchronous context, you will have to call the asynchronous version
+with
 either `.Result` or `.Wait()` to wait for the result synchronously.
 
 ```csharp
@@ -23,10 +29,10 @@ await applicationClient.DeleteApplicationAsync(applicationId);
 applicationClient.DeleteApplicationAsync(applicationId).Wait();
 ```
 
-### SubAccounts features on `AccountClient`
+#### SubAccounts features on 'AccountClient'
 
-SubAccounts features have initially been implemented by a contributor on the `AccountClient`, while the product was
-still in beta.
+SubAccounts features were initially implemented by a contributor on the `AccountClient` while the product was still in
+beta.
 With the GA release, all SubAccounts features are available on the `SubAccountsClient`, which makes previous features
 obsolete.
 
@@ -38,9 +44,9 @@ var request = GetSubAccountRequest.Parse(subAccountKey);
 var subAccount = await vonageClient.SubAccountClient.GetSubAccountAsync(request);
 ```
 
-### `CreateApplicaitonAsync` on `ApplicationClient`
+#### 'CreateApplicaitonAsync' on 'ApplicationClient'
 
-This method contains an obvious typo.
+The current method contains a typo.
 
 ```csharp
 // Using v6.X.X
@@ -50,10 +56,10 @@ var application = await applicationClient.CreateApplicaitonAsync(request);
 var application = await applicationClient.CreateApplicationAsync(request);
 ```
 
-### `CreateCall` on `VoiceClient`
+#### 'CreateCall' on 'VoiceClient'
 
-This method offers 3 different signatures.
-Only the one with a `CallCommand` parameter will remain in order to avoid primitive obsession, and rely on a proper
+This method offers three different signatures.
+Only the one with a `CallCommand` parameter will remain to avoid primitive obsession and rely on a proper
 ValueObject.
 
 ```csharp
@@ -67,10 +73,14 @@ var callResponse = voiceClient.CreateCallAsync(callCommand);
 var callResponse = voiceClient.CreateCallAsync(callCommand);
 ```
 
-### Constructors on `Credentials`
+#### Constructors on 'Credentials'
 
-Creating a Credentials instance should be done by a factory method or from a `Configuration` instance.
-Constructors will be hidden and the object will remain immutable.
+Creating a Credentials instance should be done using a factory method or from a `Configuration` instance.
+Constructors will be hidden, and the object will remain immutable.
+
+We highly recommend you to use
+our [extension methods](https://developer.vonage.com/en/blog/implicit-configuration-in-net) to dynamically
+initialize `Credentials` from your `appsettings.json` file.
 
 ```csharp
 // Using v6.X.X
@@ -87,12 +97,13 @@ var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret);
 var credentials = Credentials.FromApiKeyAndSecret(apiKey, apiSecret);
 var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret);
 var credentials = configuration.BuildCredentials();
+// Recommended
 var credentials = serviceCollection.GetRequiredService<Credentials>();
 ```
 
-### Access to Vonage URLs
+#### Access to Vonage URLs
 
-All URLs have been moved to a nested object (`VonageUrls`) to "de-bloat"the `Configuration` class, and allow
+All URLs have been moved to a nested object (`VonageUrls`) to "de-bloat" the `Configuration` class and allow
 multi-region URLs.
 
 ```csharp
@@ -109,15 +120,15 @@ var url = configuration.VonageUrls.Video;
 var url = configuration.VonageUrls.Get(VonageUrls.Region.US);
 ```
 
-## Add new timeouts on Voice Webhooks in Application API
+### Add new timeouts on Voice Webhooks in Application API
 
-Adding new timeouts requested (`connection_timeout`, `socket_timeout`) on Voice WebHooks.
+Adding new timeouts requested (`connection_timeout`, `socket_timeout`) on Voice Webhooks.
 Creating a specific structure, different from other webhooks, required to break the `Capability` inheritance.
 
-## Rename settings key from `appSettings` to `vonage`
+### Rename settings key from 'appSettings' to 'vonage'
 
-In order to make the settings more explicit and reduce chances of conflict with other libraries, the base key needs to
-be updated.
+In order to make the settings more explicit and reduce chances of conflict with other libraries, the base key has been
+updated.
 
 Using v6.X.X
 
@@ -139,17 +150,17 @@ Using v7.X.X and above
 }
 ```
 
-## Make StartTime nullable on Answered Webhook
+### Make StartTime nullable on Answered Webhook
 
 As defined in the [specs](https://developer.vonage.com/en/voice/voice-api/webhook-reference#answered), the `StartTime`
-is actually nullable.
+is now nullable.
 
-## Remove `EventUrl` and `EventMethod` from `ConversationAction`
+### Remove 'EventUrl' and 'EventMethod' from 'ConversationAction'
 
 As defined in the [specs](https://developer.vonage.com/en/voice/voice-api/ncco-reference#conversation),
-the `Conversation` action doesn't have an `EventUrl` or an `EventMethod`. 
+the `Conversation` action doesn't have an `EventUrl` or an `EventMethod`.
 
-## Make `From` mandatory in VerifyV2 WhatsApp workflow
+### Make 'From' mandatory in VerifyV2 WhatsApp workflow
 
 The `From` property used to be optional - it is now mandatory.
 
@@ -160,4 +171,4 @@ var workflow =  WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber);
 
 // Using v7.X.X and above
 var workflow =  WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber);
-```
+```