docs(api): rewrite the index page

Author: skipjack

src/content/api/cli.md

@@ -17,11 +17,9 @@ related:
     url: https://medium.com/@nimgrg/analysing-and-minimising-the-size-of-client-side-bundle-with-webpack-and-source-map-explorer-41096559beca#.c3t2srr8x
 ---
 
-webpack provides a Command Line Interface (CLI) to configure and interact with your build. This is mostly useful in case of early prototyping, profiling, writing npm scripts or personal customization of the build.
-
 For proper usage and easy distribution of this configuration, webpack can be configured with `webpack.config.js`. Any parameters sent to the CLI will map to a corresponding parameter in the config file.
 
-Have a look at the [installation guide](/guides/installation) unless you have webpack already running.
+Have a look at the [installation guide](/guides/installation) if you don't already have webpack installed.
 
 T> The new CLI for webpack is under development. New features are being added such as the `--init` flag. [Check it out!](https://github.com/webpack/webpack-cli)
 

src/content/api/index.md

@@ -3,9 +3,39 @@ title: Introduction
 sort: 1
 ---
 
-The following interfaces provide access to the compilation process in different ways:
+A variety of interfaces are available to customize the compilation process. Some features overlap between interfaces, e.g. a configuration option may be available via a CLI flag, while others exist only through a single interface. The following high-level information should get you started.
 
-* [CLI](/api/cli)
-* [Node](/api/node)
-* [Loaders](/api/loaders)
-* [Plugins](/api/plugins)
+
+## CLI
+
+The Command Line Interface (CLI) to configure and interact with your build. It is especially useful in the case of early prototyping and profiling. For the most part, the CLI is simply used to kick off the process using a configuration file and a few flags (e.g. `--env`).
+
+[Learn more!](/api/cli)
+
+
+## Module
+
+When processing modules with webpack, it is important to understand the different module syntaxes -- specifically the [methods](/api/module-methods) and [variables](/api/module-variables) -- that are supported.
+
+[Learn more!](/api/module-methods)
+
+
+## Node
+
+While most users can get away with just using the CLI along with a configuration file, more fine-grained control of the compilation can be achieved via the Node interface. This includes passing multiple configurations, programatically running or watching, and collecting stats.
+
+[Learn more!](/api/node)
+
+
+## Loaders
+
+Loaders are transformations that are applied to the source code of a module. They are written as functions that take accept source code as a parameter and return a new version of that code with tranformations applied.
+
+[Learn more!](/api/loaders)
+
+
+## Plugins
+
+The plugin interface provided by webpack allows users to tap directly into the compilation process. Plugins can register handlers on lifecycle hooks that run at different points in the compilation process. When each hook is executed, the plugin will have full access to the current state of the compilation.
+
+[Learn more!](/api/plugins)

src/content/api/loaders.md

@@ -4,13 +4,8 @@ sort: 4
 contributors:
     - TheLarkInn
     - jhnns
-
 ---
 
-Loaders are transformations that are applied on the source code of a module. They are functions (running in Node.js) that take the source of a resource file as the parameter and return the new source.
-
-## How to write a loader
-
 A loader is just a JavaScript module that exports a function. The [loader runner](https://github.com/webpack/loader-runner) calls this function and passes the result of the previous loader or the resource file into it. The `this` context of the function is filled-in by webpack and the [loader runner](https://github.com/webpack/loader-runner) with some useful methods that allow the loader (among other things) to change its invocation style to async, or get query parameters.
 
 The first loader is passed one argument: the content of the resource file. The compiler expects a result from the last loader. The result should be a `String` or a `Buffer` (which is converted to a string), representing the JavaScript source code of the module. An optional SourceMap result (as JSON object) may also be passed.

src/content/api/plugins.md

@@ -1,12 +1,10 @@
 ---
 title: Plugin API
 group: Plugins
-sort: 1
+sort: 0
 ---
 
-T> For a high-level introduction to writing plugins, start with [How to write a plugin](/development/how-to-write-a-plugin).
-
-webpack provides flexible and powerful customization api in the form of plugins. Using plugins, we can plug functionality into webpack. Additionally, webpack provides lifecycle hooks into which plugins can be registered. At each of these lifecycle points, webpack will run all of the registered plugins and provide them with the current state of the webpack compilation.
+T> For a high-level introduction to writing plugins, start with [writing a plugin](/contribute/writing-a-plugin).
 
 Many objects in webpack extend the `Tapable` class, which exposes a `plugin` method. And with the `plugin` method, plugins can inject custom build steps. You will see `compiler.plugin` and `compilation.plugin` used a lot. Essentially, each one of these plugin calls binds a callback to fire at specific steps throughout the build process.