Restructure documentation layout

docs/guides/concepts/events.md

@@ -0,0 +1,28 @@
+---
+title: Events
+---
+
+# Events
+
+Messages from Discord are exposed via events, and follow a pattern of `Func<[event params], Task>`, which allows you to easily create either async or sync event handlers.
+
+To hook into events, you must be using the @Discord.WebSocket.DiscordSocketClient, which provides WebSocket capabilities, necessary for receiving events.
+
+>[!NOTE]
+>The gateway will wait for all registered handlers of an event to finish before raising the next event. As a result of this, it is reccomended that if you need to perform any heavy work in an event handler, it is done on its own thread or Task.
+
+**For further documentation of all events**, it is reccomended to look at the [Events Section](xref:Discord.WebSocket.DiscordSocketClient#events) on the API documentation of @Discord.WebSocket.DiscordSocketClient
+
+## Connection State
+
+Connection Events will be raised when the Connection State of your client changes.
+
+[DiscordSocketClient.Connected](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_Connected) and [Disconnected](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_Disconnected) are raised when the Gateway Socket connects or disconnects, respectively.
+
+>[!WARNING]
+>You should not use DiscordClient.Connected to run code when your client first connects to Discord. The client has not received and parsed the READY event and guild stream yet, and will have an incomplete or empty cache.
+
+[DiscordSocketClient.Ready](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_Ready) is raised when the `READY` packet is parsed and received from Discord.
+
+>[!NOTE]
+>The [DiscordSocketClient.ConnectAsync](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_ConnectAsync_System_Boolean_) method will not return until the READY packet has been processed. By default, it also will not return until the guild stream has finished. This means it is safe to run bot code directly after awaiting the ConnectAsync method.

docs/guides/concepts/logging.md

@@ -0,0 +1,42 @@
+---
+title: Logging
+---
+
+Discord.Net's clients provide a [Log] event that all messages will be
+disbatched over.
+
+For more information about events in Discord.Net, see the [Events]
+section.
+
+[Log]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log
+[Events]: events.md
+
+### Usage
+
+To receive log events, simply hook the discord client's log method
+to a Task with a single parameter of type [LogMessage]
+
+It is recommended that you use an established function instead of a
+lambda for handling logs, because most [addons] accept a reference
+to a logging function to write their own messages.
+
+### Usage in Commands
+
+Discord.Net's [CommandService] also provides a log event, identical
+in signature to other log events.
+
+Data logged through this event is typically coupled with a
+[CommandException], where information about the command's context
+and error can be found and handled.
+
+#### Samples
+
+[!code-csharp[Logging Sample](samples/logging.cs)]
+
+#### Tips
+
+Due to the nature of Discord.Net's event system, all log event
+handlers will be executed synchronously on the gateway thread. If your
+log output will be dumped to a Web API (e.g. Sentry), you are advised
+to wrap your output in a `Task.Run` so the gateway thread does not
+become blocked while waiting for logging data to be written.

docs/guides/concepts/samples/logging.cs

@@ -0,0 +1,29 @@
+using Discord;
+using Discord.WebSocket;
+
+public class Program
+{
+	private DiscordSocketClient _client;
+	static void Main(string[] args) => new Program().MainAsync().GetAwaiter().GetResult();
+	
+	public async Task MainAsync()
+	{
+		_client = new DiscordSocketClient(new DiscordSocketConfig
+		{
+			LogLevel = LogSeverity.Info
+		});
+
+		_client.Log += Log;
+
+		await _client.LoginAsync(TokenType.Bot, "bot token");
+		await _client.StartAsync();
+		
+		await Task.Delay(-1);
+	}
+
+	private Task Log(LogMessage message)
+	{
+		Console.WriteLine(message.ToString());
+		return Task.CompletedTask;
+	}
+}