Restructure documentation layout

docs/guides/migrating/migrating.md

@@ -0,0 +1,61 @@
+# Migrating from 0.9
+
+**1.0.0 is the biggest breaking change the library has gone through, due to massive
+changes in the design of the library.**
+
+>A medium to advanced understanding is recommended when working with this library.
+
+It is recommended to familiarize yourself with the entities in 1.0 before continuing. 
+Feel free to look through the library's source directly, look through IntelliSense, or 
+look through our hosted [API Documentation](xref:Discord).
+
+## Entities 
+
+Most API models function _similarly_ to 0.9, however their names have been changed. 
+You should also keep in mind that we now separate different types of Channels and Users.
+
+Before proceeding, please read over @Terminology to understand the naming behind some objects.
+
+Below is a table that compares most common 0.9 entities to their 1.0 counterparts.
+
+>This should be used mostly for migration purposes. Please take some time to consider whether
+>or not you are using the right "tool for the job" when working with 1.0
+
+| 0.9 | 1.0 | Notice |
+| --- | --- | ------ |
+| Server | @Discord.WebSocket.SocketGuild |
+| Channel | @Discord.WebSocket.SocketGuildChannel | Applies only to channels that are members of a Guild |
+| Channel.IsPrivate | @Discord.WebSocket.SocketDMChannel
+| ChannelType.Text | @Discord.WebSocket.SocketTextChannel | This applies only to Text Channels in Guilds
+| ChannelType.Voice | @Discord.WebSocket.SocketVoiceChannel | This applies only to Voice Channels in Guilds
+| User | @Discord.WebSocket.SocketGuildUser | This applies only to users belonging to a Guild*
+| Profile | @Discord.WebSocket.SocketGuildUser
+| Message | @Discord.WebSocket.SocketUserMessage
+
+\* To retrieve an @Discord.WebSocket.SocketGuildUser, you must retrieve the user from an @Discord.WebSocket.SocketGuild.
+
+## Event Registration
+
+Prior to 1.0, events were registered using the standard c# `Handler(EventArgs)` pattern. In 1.0,
+events are delegates, but are still registered the same.
+
+For example, let's look at [DiscordSocketClient.MessageReceived](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_MessageReceived)
+
+To hook an event into MessageReceived, we now use the following code:  
+[!code-csharp[Event Registration](guides/samples/migrating/event.cs)]
+
+> **All Event Handlers in 1.0 MUST return Task!**
+
+If your event handler is marked as `async`, it will automatically return `Task`. However,
+if you do not need to execute asynchronus code, do _not_ mark your handler as `async`, and instead,
+stick a `return Task.CompletedTask` at the bottom.
+
+[!code-csharp[Sync Event Registration](guides/samples/migrating/sync_event.cs)]
+
+**Event handlers no longer require a sender.** The only arguments your event handler needs to accept
+are the parameters used by the event. It is recommended to look at the event in IntelliSense or on the
+API docs before implementing it.
+
+## Async
+
+Nearly everything in 1.0 is an async Task. You should always await any tasks you invoke.