updated readme

README.md

@@ -1,8 +1,8 @@
 # Xamarin.Cognitive.BingSpeech ![NuGet](https://img.shields.io/nuget/v/Xamarin.Cognitive.BingSpeech.svg?label=NuGet)
 
-`Xamarin.Cognitive.BingSpeech` is a managed client library that makes it easy to work with the [Microsoft Cognitive Services Bing Speech API](https://azure.microsoft.com/en-us/services/cognitive-services/speech/) on Xamarin.iOS, Xamarin.Android, Xamarin.Forms, and other Portable Class Library (PCL) projects.
+`Xamarin.Cognitive.BingSpeech` is a managed client library that makes it easy to work with the [Microsoft Cognitive Services Bing Speech API](https://azure.microsoft.com/en-us/services/cognitive-services/speech/) on Xamarin.iOS, Xamarin.Android, Xamarin.Forms, UWP, and other .NET Standard 2.0 projects.
 
-Includes a Xamarin.Forms sample with iOS and Android apps.
+Includes a Xamarin.Forms sample with iOS, Android, and UWP apps.
 
 Resources about the Bing Speech API and what it is:
 
@@ -14,25 +14,31 @@ Resources about the Bing Speech API and what it is:
 
 Why use this client library to talk to the Bing Speech API and not [insert other lib or sample code here]?
 
-- The official C# SDK is made with Windows in mind, not Xamarin.
+- The official C# SDK is made with Windows in mind, not Xamarin/mobile.
 - Many/most other Xamarin-based examples or sample apps I've found:
 	- Use an older version of the Bing Speech API.
-	- Use the older `HttpWebRequest` API.
+	- Use the older `HttpWebRequest` network APIs.
 	- Contain very little in the way of feature support.
-	- Arent mobile specific or don't contain mobile examples
+	- Are not mobile specific or don't contain mobile examples/value-adds
 
-I wanted to create something specific to mobile, that was updated and easy to use.
+I wanted to create something specific to mobile, that was updated, easy to use, and included some niceties specific to the mobile world.
 
 
 # Features
 
-- 100% `HttpClient`-based, managed code
+- 100% `HttpClient`-based, managed code (.NET Standard 2.0)
 - Works with the latest version of the Bing Speech API
 - Advanced Bing Speech API feature support, such as:
 	- Chunked transfer encoding for efficient audio streaming to server
-	- Three recognition modes: Interactive, Conversation, Dictation
-	- Simple or Detailed Output Mode
-	- 3 profanity modes: Masked, Removed, or Raw
+	- Three recognition modes:
+    	- Interactive
+    	- Conversation
+    	- Dictation
+	- Simple vs. Detailed Output Mode
+	- 3 profanity modes:
+    	- Masked
+    	- Removed
+    	- Raw
 	- Recognition language support
 - Ability to stream audio to the server as it's being recorded
 - Easy to use API
@@ -41,28 +47,30 @@ I wanted to create something specific to mobile, that was updated and easy to us
 
 # Setup
 
-`Xamarin.Cognitive.BingSpeech` is available as a [NuGet package](https://www.nuget.org/packages/Xamarin.Cognitive.BingSpeech/) to be added to your Xamarin.iOS, Xamarin.Android, Xamarin.Forms, or UWP project(s).
-
-The included PCL assembly is compiled against Profile 111, which is currently the same profile used for PCL-based Xamarin.Forms solutions.
+`Xamarin.Cognitive.BingSpeech` is available as a [NuGet package](https://www.nuget.org/packages/Xamarin.Cognitive.BingSpeech/) to be added to your Xamarin.iOS, Xamarin.Android, Xamarin.Forms, UWP, or other .NET Standard 2.0 project(s).
 
 You must have a valid Bing Speech API subscription key.  You can get a free trial key or create a permanent key in the [Bing Speech API portal](https://azure.microsoft.com/en-us/services/cognitive-services/speech/).
 
-Once you have an API key, update the `keys.cs` file so the `SubscriptionKey` property is set to your API key:
+Once you have an API key, you can construct an instance of the client:
 
 ```C#
-public const string SubscriptionKey = "My Key Goes Here";
+var bingSpeechClient = new BingSpeechApiClient ("<YOUR KEY>");
 ```
 
+Read more details on [how to use the client below](https://github.com/NateRickard/Xamarin.Cognitive.BingSpeech#usage).
+
+To run the sample(s), update the `keys.cs` file so the `SubscriptionKey` property is set to your API key:
 
-## Platform Configuration
+```C#
+public const string SubscriptionKey = "My Key Goes Here";
+```
 
-**Note** if you're using the [Audio Recorder Plugin](https://www.nuget.org/packages/Plugin.AudioRecorder/) to record audio to send to the Bing Speech API, you'll want to review the [platform-specific permissions required for each platform](https://github.com/NateRickard/Plugin.AudioRecorder#permissions) there for accessing the microphone and recording audio.
 
-### HttpClient configuration
+## Platform-Specific Configuration
 
-When using the Bing Speech API, you must use one of the native `HttpClient` implementations that support the TLS 1.2 stack.
+All app platforms should have 'Internet' or similar permissions in order to communicate with the Bing Speech API.  Outside of this, no platform specific config is required for this library to function.
 
-Please review the [documentation here](https://developer.xamarin.com/guides/cross-platform/transport-layer-security/) for more information about what this means and how to implement these on each platform.  The included sample apps use the `NSUrlSession` (iOS) and `AndroidClientHandler` (Android) implementations and these are recommended.
+**Note:** if you're using the [Audio Recorder Plugin](https://www.nuget.org/packages/Plugin.AudioRecorder/) (or likely any other method of recording audio) to send audio to the Bing Speech API, you'll want to review the [platform-specific permissions required for each platform](https://github.com/NateRickard/Plugin.AudioRecorder#required-permissions--capabilities) there for accessing the microphone and recording audio.
 
 
 # Usage
@@ -72,10 +80,10 @@ The [sample app](https://github.com/NateRickard/Xamarin.Cognitive.BingSpeech/tre
 The first thing you'll need to do is construct a new instance of the Bing Speech API client that will be used for your API calls:
 
 ```C#
-BingSpeechApiClient bingSpeechClient = new BingSpeechApiClient ("My Bing Speech API Subscription Key");
+BingSpeechApiClient bingSpeechClient = new BingSpeechApiClient ("<YOUR API KEY>");
 ```
 
-The Bing Speech API has two distinct output modes that yeild different results.  More information on each output mode [can be found in the documentation](https://docs.microsoft.com/en-us/azure/cognitive-services/speech/api-reference-rest/bingvoicerecognition#output-format).
+The Bing Speech API has two distinct output modes that yield different results.  More information on each output mode [can be found in the documentation](https://docs.microsoft.com/en-us/azure/cognitive-services/speech/api-reference-rest/bingvoicerecognition#output-format).
 
 
 ## Simple Output Mode
@@ -215,27 +223,27 @@ public class SpeechResult
 
 It's also possible to send audio to the server from a `Stream`.  The most common use of this would be to start sending audio data to the Bing Speech API as it's still being recorded.
 
-In addition to the audio `Stream`, you also need to provide the sample rate, and, optionally, a `Task` object that will indicate when the audio stream has finished recording.  If the `Task` is omitted, the client library will attempt to make additonal reads from the stream until no further audio data is detected; hwoever, this is not recommended.
+In addition to the audio `Stream`, you also need to provide the sample rate, and, optionally, a `Task` object that will indicate when the audio stream has finished recording.  If the `Task` is omitted, the client library will attempt to make additional reads from the stream until no further audio data is detected; however, this is not recommended.
 
 ```C#
-//simple output mode
+// simple output mode
 
 var simpleResult = await bingSpeechClient.SpeechToTextSimple (stream, <sample rate>, <audio record Task>);
 
-//... or detailed output mode
+// ... or detailed output mode
 
 var detailedResult = await bingSpeechClient.SpeechToTextDetailed (stream, <sample rate>, <audio record Task>);
 ```
 
 Since this library was developed with my [audio recorder plugin](https://github.com/NateRickard/Plugin.AudioRecorder) in mind, this has been made quite simple:
 
 ```C#
-//start recording audio
+// start recording audio
 var audioRecordTask = await recorder.StartRecording ();
 
 using (var stream = recorder.GetAudioFileStream ())
 {
-	//this will begin sending the recording audio data as it continues to record
+	// this will begin sending the recording audio data as it continues to record
 	var simpleResult = await bingSpeechClient.SpeechToTextSimple (stream, recorder.AudioStreamDetails.SampleRate, audioRecordTask);
 }
 ```