Add web build docs, many other minor doc changes

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 If you wish to contribute to the discord.js codebase or documentation, feel free to fork the repository and submit a
 pull request. We use ESLint to enforce a consistent coding style, so having that set up in your editor of choice
-is a great boon to your coding process.
+is a great boon to your development process.
 
 ## Setup
 To get ready to work on the codebase, please do the following:

README.md

@@ -27,7 +27,7 @@ discord.js is a powerful node.js module that allows you to interact with the
 
 ## Installation
 **Node.js 6.0.0 or newer is required.**  
-Ignore any warnings about unmet peer dependencies - all peer dependencies are optional.
+Ignore any warnings about unmet peer dependencies, as they're are optional.
 
 Without voice support: `npm install discord.js --save`  
 With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save`  
@@ -62,19 +62,11 @@ client.login('your token');
 
 A bot template using discord.js can be generated using [generator-discordbot](https://www.npmjs.com/package/generator-discordbot).
 
-## Web distributions
-Web builds of discord.js that are fully capable of running in browsers are available [here](https://github.com/hydrabolt/discord.js/tree/webpack).
-These are built using [Webpack 2](https://webpack.js.org/). The API is identical, but rather than using `require('discord.js')`,
-the entire `Discord` object is available as a global (on the `window` object).
-The ShardingManager and any voice-related functionality is unavailable in these builds.
-
 ## Links
-* [Website](https://discord.js.org/)
+* [Website](https://discord.js.org/) ([source](https://github.com/hydrabolt/discord.js-site))
+* [Documentation](https://discord.js.org/#/docs)
 * [Discord.js server](https://discord.gg/bRCvFy9)
 * [Discord API server](https://discord.gg/rV4BwdK)
-* [Documentation](https://discord.js.org/#/docs)
-* [Legacy (v8) documentation](http://discordjs.readthedocs.io/en/8.2.0/docs_client.html)
-* [Examples](https://github.com/hydrabolt/discord.js/tree/master/docs/examples)
 * [GitHub](https://github.com/hydrabolt/discord.js)
 * [NPM](https://www.npmjs.com/package/discord.js)
 * [Related libraries](https://discordapi.com/unofficial/libs.html) (see also [discord-rpc](https://www.npmjs.com/package/discord-rpc))

docs/examples/avatars.js

@@ -6,19 +6,19 @@
 const Discord = require('discord.js');
 
 // create an instance of a Discord Client, and call it bot
-const bot = new Discord.Client();
+const client = new Discord.Client();
 
 // the token of your bot - https://discordapp.com/developers/applications/me
 const token = 'your bot token here';
 
 // the ready event is vital, it means that your bot will only start reacting to information
 // from Discord _after_ ready is emitted.
-bot.on('ready', () => {
+client.on('ready', () => {
   console.log('I am ready!');
 });
 
 // create an event listener for messages
-bot.on('message', message => {
+client.on('message', message => {
   // if the message is "what is my avatar",
   if (message.content === 'what is my avatar') {
     // send the user's avatar URL
@@ -27,4 +27,4 @@ bot.on('message', message => {
 });
 
 // log our bot in
-bot.login(token);
+client.login(token);

docs/examples/ping.js

@@ -5,20 +5,20 @@
 // import the discord.js module
 const Discord = require('discord.js');
 
-// create an instance of a Discord Client, and call it bot
+// create an instance of a Discord Client
-const bot = new Discord.Client();
+const client = new Discord.Client();
 
 // the token of your bot - https://discordapp.com/developers/applications/me
 const token = 'your bot token here';
 
 // the ready event is vital, it means that your bot will only start reacting to information
 // from Discord _after_ ready is emitted.
-bot.on('ready', () => {
+client.on('ready', () => {
   console.log('I am ready!');
 });
 
 // create an event listener for messages
-bot.on('message', message => {
+client.on('message', message => {
   // if the message is "ping",
   if (message.content === 'ping') {
     // send "pong" to the same channel.
@@ -27,4 +27,4 @@ bot.on('message', message => {
 });
 
 // log our bot in
-bot.login(token);
+client.login(token);

docs/general/welcome.md

@@ -31,7 +31,7 @@ discord.js is a powerful node.js module that allows you to interact with the
 
 ## Installation
 **Node.js 6.0.0 or newer is required.**  
-Ignore any warnings about unmet peer dependencies - all of them are optional.
+Ignore any warnings about unmet peer dependencies, as they're are optional.
 
 Without voice support: `npm install discord.js --save`  
 With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save`  
@@ -43,29 +43,42 @@ Using opusscript is only recommended for development environments where node-opu
 For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers.
 
 ### Optional packages
-- [uws](https://www.npmjs.com/package/uws) for much a much faster WebSocket connection (`npm install uws --save`)
+- [uws](https://www.npmjs.com/package/uws) for a much faster WebSocket connection (`npm install uws --save`)
 - [erlpack](https://github.com/hammerandchisel/erlpack) for significantly faster WebSocket data (de)serialisation (`npm install hammerandchisel/erlpack --save`)
 
-## Web distributions
+## Example Usage
-Web builds of discord.js that are fully capable of running in browsers are available [here](https://github.com/hydrabolt/discord.js/tree/webpack).
+```js
-These are built by [Webpack 2](https://webpack.js.org/). The API is identical, but rather than using `require('discord.js')`,
+const Discord = require('discord.js');
-the entire `Discord` object is available as a global (on the `window` object).
+const client = new Discord.Client();
-The ShardingManager and any voice-related functionality is unavailable in these builds.
 
-## Guides
+client.on('ready', () => {
-* [LuckyEvie's general guide](https://eslachance.gitbooks.io/discord-js-bot-guide/content/)
+  console.log('I am ready!');
-* [York's v9 upgrade guide](https://yorkaargh.wordpress.com/2016/09/03/updating-discord-js-bots/)
+});
+
+client.on('message', message => {
+  if (message.content === 'ping') {
+    message.reply('pong');
+  }
+});
+
+client.login('your token');
+```
+
+A bot template using discord.js can be generated using [generator-discordbot](https://www.npmjs.com/package/generator-discordbot).
 
 ## Links
-* [Website](https://discord.js.org/)
+* [Website](https://discord.js.org/) ([source](https://github.com/hydrabolt/discord.js-site))
+* [Documentation](https://discord.js.org/#/docs)
 * [Discord.js server](https://discord.gg/bRCvFy9)
 * [Discord API server](https://discord.gg/rV4BwdK)
-* [Documentation](https://discord.js.org/#/docs)
-* [Legacy (v8) documentation](http://discordjs.readthedocs.io/en/8.2.0/docs_client.html)
-* [Examples](https://github.com/hydrabolt/discord.js/tree/master/docs/examples)
 * [GitHub](https://github.com/hydrabolt/discord.js)
 * [NPM](https://www.npmjs.com/package/discord.js)
-* [Related libraries](https://discordapi.com/unofficial/libs.html)
+* [Related libraries](https://discordapi.com/unofficial/libs.html) (see also [discord-rpc](https://www.npmjs.com/package/discord-rpc))
+
+## Contributing
+Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the
+[documentation](https://discord.js.org/#/docs).  
+See [the contribution guide](CONTRIBUTING.md) if you'd like to submit a PR.
 
 ## Help
 If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle

docs/index.yml

@@ -6,6 +6,10 @@
       path: updating.md
     - name: FAQ
       path: faq.md
+- name: Topics
+  files:
+    - name: Web builds
+      path: web.md
 - name: Examples
   files:
     - name: Ping

docs/topics/web.md

@@ -0,0 +1,38 @@
+# Web builds
+In addition to your usual Node applications, discord.js has special distributions available that are capable of running in web browsers.
+This is useful for client-side web apps that need to interact with the Discord API.
+[Webpack 2](https://webpack.js.org/) is used to generate these builds
+
+## Usage
+You can obtain your desired version of discord.js' web build from the [webpack branch](https://github.com/hydrabolt/discord.js/tree/webpack) of the GitHub repository.
+There is a file for each branch and version of the library, and the ones ending in `.min.js` are minified to substantially reduce the size of the source code.
+
+Include the file on the page just as you would any other JS library, like so:
+```html
+<script type="text/javascript" src="discord.VERSION.min.js"></script>
+```
+
+Rather than importing discord.js with `require('discord.js')`, the entire `Discord` object is available as a global (on the `window`) object.
+The usage of the API isn't any different from using it in Node.js.
+
+## Restrictions
+- Any voice-related functionality is unavailable, as there is currently no audio encoding/decoding capabilities without external native libraries,
+  which web browsers do not support.
+- The ShardingManager cannot be used, since it relies on being able to spawn child processes for shards.
+- Neither of the optional packages (uws and erlpack) are usable, since they're native libraries.
+
+## Example
+```html
+<script type="text/javascript" src="discord.11.0.0.min.js"></script>
+<script type="text/javascript">
+  const client = new Discord.Client();
+
+  client.on('message', msg => {
+    const guildTag = msg.channel.type === 'text' ? `[${msg.guild.name}]` : '[DM]';
+    const channelTag = msg.channel.type === 'text' ? `[#${msg.channel.name}]` : '';
+    console.log(`${guildTag}${channelTag} ${msg.author.username}#${msg.author.discriminator}: ${msg.content}`);
+  });
+
+  client.login('some crazy token');
+</script>
+```