Merge 2990bb8261 into e764dafe08

docs/guides/getting_started/installing.md

@@ -2,10 +2,10 @@
 title: Installing Discord.Net
 ---
 
-Discord.Net is distributed through the NuGet package manager, and it
-is recommended to use NuGet to get started.
+Discord.Net is distributed through the NuGet package manager, and we 
+recommend installing Discord.Net with NuGet.
 
-Optionally, you may compile from source and install yourself.
+Alternatively, you may compile from source and install yourself.
 
 # Supported Platforms
 
@@ -13,10 +13,9 @@ Currently, Discord.Net targets [.NET Standard] 1.3 and offers support
 for .NET Standard 1.1. If your application will be targeting .NET
 Standard 1.1, please see the [additional steps].
 
-Since Discord.Net is built on the .NET Standard, it is also
-recommended to create applications using [.NET Core], though not 
-required. When using .NET Framework, it is suggested to target
-`.NET Framework 4.6.1` or higher.
+Since Discord.Net is built on the .NET Standard, we recommend you
+creating applications using [.NET Core]. When using .NET Framework, 
+you should target `.NET Framework 4.6.1` or higher.
 
 [.NET Standard]: https://docs.microsoft.com/en-us/dotnet/articles/standard/library
 [.NET Core]: https://docs.microsoft.com/en-us/dotnet/articles/core/
@@ -86,7 +85,7 @@ you're installing from the developer feed.
 
 # Compiling from Source
 
-In order to compile Discord.Net, you require the following:
+In order to compile Discord.Net, acquire the following:
 
 ### Using Visual Studio
 
@@ -104,27 +103,27 @@ Studio installation.
 
 ## Installing on .NET Standard 1.1
 
-For applications targeting a runtime corresponding with .NET Standard
-1.1 or 1.2, the builtin WebSocket and UDP provider will not work. For
-applications which utilize a WebSocket connection to Discord
-(WebSocket or RPC), third-party provider packages will need to be
-installed and configured.
+For applications targeting a runtime environment corresponding with 
+.NET Standard 1.1 or 1.2, the built-in WebSocket and UDP provider will 
+not work. Install and configure third-party provider packages for 
+applications utilizing a WebSocket or an RPC connection to Discord.
 
-First, install the following packages through NuGet, or compile
-yourself, if you prefer:
+1. Install the following packages through NuGet, or compile the 
+following packages yourself:
 
 - Discord.Net.Providers.WS4Net
 - Discord.Net.Providers.UDPClient
 
-Note that `Discord.Net.Providers.UDPClient` is _only_ required if your
-bot will be utilizing voice chat.
+>[!NOTE]
+`Discord.Net.Providers.UDPClient` is _only_ required if your bot will 
+be utilizing voice chat.
 
-Next, you will need to configure your [DiscordSocketClient] to use
-these custom providers over the default ones.
+2. Configure your [DiscordSocketClient] to use these third-party 
+providers over the default ones.
 
-To do this, set the `WebSocketProvider` and the optional
-`UdpSocketProvider` properties on the [DiscordSocketConfig] that you
-are passing into your client.
+Set the `WebSocketProvider` and optionally the `UdpSocketProvider` 
+properties in the [DiscordSocketConfig] and pass the config into 
+your client.
 
 [!code-csharp[NET Standard 1.1 Example](samples/netstd11.cs)]
 

docs/guides/getting_started/intro.md

@@ -4,14 +4,13 @@ title: Getting Started
 
 # Making a Ping-Pong bot
 
-One of the first steps to getting started with the Discord API is to
-write a basic ping-pong bot. We will expand on this to create more
-diverse commands later, but for now, it is a good starting point.
+This topic introduces the Discord API by instructing you to 
+write a ping-pong bot who can respond message 'ping' with 
+'pong'. We would create more diverse commands for the bot later.
 
 ## Creating a Discord Bot
 
-Before you can begin writing your bot, it is necessary to create a bot
-account on Discord.
+Before writing your bot, create a bot account on Discord.
 
 1. Visit the [Discord Applications Portal].
 2. Create a New Application.
@@ -34,10 +33,11 @@ other options!**
 ## Adding your bot to a server
 
 Bots **cannot** use invite links, they must be explicitly invited
-through the OAuth2 flow.
+through the OAuth2 flow, the industry-standard protocol for 
+authorization. 
 
 1. Open your bot's application on the [Discord Applications Portal].
-2. Retrieve the app's **Client ID**.
+2. Retrieve the application's **Client ID**.
 	
 	![Step 2](images/intro-client-id.png)
 	
@@ -49,7 +49,7 @@ through the OAuth2 flow.
 	
 	>[!NOTE]
 	Only servers where you have the `MANAGE_SERVER` permission will be
-	present in this list.
+	present in the dropdown menu.
 	
 	![Step 6](images/intro-add-bot.png)
 
@@ -64,20 +64,18 @@ do that now. (see the [Installing](installing.md) section)
 Discord.Net uses .NET's [Task-based Asynchronous Pattern (TAP)]
 extensively - nearly every operation is asynchronous.
 
-It is highly recommended that these operations are awaited in a
-properly established async context whenever possible. Establishing an
-async context can be problematic, but not hard.
+We suggest that asynchronous operations should await in an established 
+async context whenever possible.
 
-To do so, we will be creating an async main in your console
-application, and rewriting the static main method to invoke the new
-async main.
+To establish an async context, create an async main method in your 
+console application, and rewrite the static main method to invoke the
+new async main.
 
 [!code-csharp[Async Context](samples/intro/async-context.cs)]
 
-As a result of this, your program will now start and immediately
-jump into an async context. This will allow us to create a connection 
-to Discord later on without needing to worry about setting up the
-correct async implementation.
+Your program will immediately jump into an async context when starts. 
+This will allow us to create a connection to Discord later on without 
+worrying about setting up the correct async implementation.
 
 >[!TIP]
 If your application throws any exceptions within an async context,
@@ -93,7 +91,7 @@ async main **will** cause the application to crash.
 ### Creating a logging method
 
 Before we create and configure a Discord client, we will add a method
-to handle Discord.Net's log events.
+to handle Discord.Net's log events. Check the concept of [logging data].
 
 To allow agnostic support of as many log providers as possible, we
 log information through a `Log` event with a proprietary `LogMessage`
@@ -105,23 +103,24 @@ the Console.
 
 [!code-csharp[Async Context](samples/intro/logging.cs)]
 
+[logging data]:../concepts/logging.md
 [API Documentation]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log
 
 ### Creating a Discord Client
 
 Finally, we can create a connection to Discord. Since we are writing
 a bot, we will be using a [DiscordSocketClient] along with socket
-entities. See the [terminology](terminology.md) if you're unsure of
-the differences.
+entities. See the [terminology](terminology.md) if you're unsure 
+the differences among `Discord.Net.Rest`, `Discord.Net.Rpc`, 
+and `Discord.Net.WebSocket`.
 
 To do so, create an instance of [DiscordSocketClient] in your async
 main, passing in a configuration object only if necessary. For most
 users, the default will work fine.
 
 Before connecting, we should hook the client's `Log` event to the
-log handler that was just created. Events in Discord.Net work
-similarly to other events in C#, so hook this event the way that
-you typically would.
+log handler that you just created. Events in Discord.Net work
+similarly to other events in C#. [An Overview of Events in C#]
 
 Next, you will need to "login to Discord" with the `LoginAsync` 
 method.
@@ -139,15 +138,15 @@ the source code for your bot.
 
 We may now invoke the client's `StartAsync` method, which will
 start connection/reconnection logic. It is important to note that
-**this method returns as soon as connection logic has been started!**
+**`StartAsync` method returns as soon as connection logic has been started!**
 
 Any methods that rely on the client's state should go in an event
 handler.
 
-Finally, we will want to block the async main method from returning
-until after the application is exited. To do this, we can await an
-infinite delay or any other blocking method, such as reading from
-the console.
+Finally, we will want to block the async main method from returning 
+when running the application. To block from returning, we can await 
+an infinite delay or any other blocking method, such as reading 
+from the console.
 
 The following lines can now be added:
 
@@ -162,6 +161,7 @@ This means that you are targeting a platform where .NET's default
 WebSocket client is not supported. Refer to the [installation guide]
 for how to fix this.
 
+[An Overview of Events in C#]:https://docs.microsoft.com/en-us/dotnet/csharp/events-overview
 [DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
 [installation guide]: installing.md#installing-on-net-standard-11
 
@@ -207,7 +207,7 @@ You should have now added the following lines:
 
 Now your first bot is complete. You may continue to add on to this
 if you desire, but for any bots that will be carrying out multiple
-commands, it is strongly recommended to use the command framework as
+commands, we strongly recommend you using the command framework as
 shown below.
 
 For your reference, you may view the [completed program].
@@ -229,9 +229,8 @@ For reference, view an [annotated example] of this structure.
 
 [annotated example]: samples/intro/structure.cs
 
-It is important to know that the recommended design pattern of bots
-should be to separate the program (initialization and command handler),
+Separating the program (initialization and command handler),
 the modules (handle commands), and the services (persistent storage,
-pure functions, data manipulation).
+pure functions, data manipulation) is a nice design pattern for bot.
 
-**todo:** diagram of bot structure
+**todo:** diagram of bot structure