Updates

docs/00 Quick Start/Overview.md

@@ -3,11 +3,12 @@ Overview
 
 React DnD is unlike most of the drag and drop libraries out there, and it can be intimidating if you've never used it before. However, once you get a taste of a few concepts at the heart of its design, it starts to make sense. I suggest you read about these concepts before the rest of the docs.
 
-Some of these concepts may seem to have a certain familiarity to the ideas from the [Flux architecture](http://facebook.github.io/flux/). This is not a coincidence, as React DnD uses Flux internally.
+Some of these concepts may seem to have a certain resemblance to the [Flux architecture](http://facebook.github.io/flux/).  
+This is not a coincidence, as React DnD uses Flux internally.
 
 ### Backends
 
-React DnD is built on top of the [HTML5 drag and drop API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_and_drop). It is a reasonable default because it screenshots the dragged DOM node and uses it as a “drag preview” out of the box. It's handy because you don't have to do any drawing as the cursor moves. It also lets you handle the file drop events.
+React DnD is built on top of the [HTML5 drag and drop API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_and_drop). It is a reasonable default because it screenshots the dragged DOM node and uses it as a “drag preview” out of the box. It's handy that you don't have to do any drawing as the cursor moves. This API is also the only way to handle file drop events.
 
 Unfortunately, the HTML5 drag and drop API also has some downsides. It does not work on touch screens, and it provides less customization opportunities on IE than in other browsers.
 
@@ -120,7 +121,7 @@ The `connectDropTarget` call tells React DnD that the root DOM node of our compo
 
 So far we have covered the backends which work with the DOM, the data, as represented by the items and types, and the collecting functions that, thanks to the monitors and the connectors, let you describe what props React DnD should inject into your components.
 
-But how do we configure our components to actually have those props injected? How do we perform the side effects in response to the drag and drop events? Meet the *drag sources* and the *drop targets*, the primary abstraction units of React DnD. **They tie the types, the items, the side effects, and the collecting function together with your components.**
+But how do we configure our components to actually have those props injected? How do we perform the side effects in response to the drag and drop events? Meet the *drag sources* and the *drop targets*, the primary abstraction units of React DnD. **They really tie the types, the items, the side effects, and the collecting function together with your components.**
 
 Whenever you want to make a component or some part of it draggable, you need to wrap that component into a *drag source* declaration. Every drag source is registered for a certain *type*, and has to implement a method producing an *item* from the component's props, and optionally a few other methods for handling the drag and drop events. The drag source declaration also lets you specify the *collecting function* for the given component.
 
@@ -134,7 +135,7 @@ How do you wrap your components? What does wrapping even mean? If you have not w
 
 In React DnD, [`DragSource`](/docs-drag-source.html) and [`DropTarget`](/docs-drop-target.html), as well as a few other top-level exported functions, are in fact higher-order components. They breathe the drag and drop magic into your components.
 
-One caveat of using them is that they require *two* function applications. For example, here's how to wrap `YourClass` in a [`DragSource`](/docs-drag-source.html):
+One caveat of using them is that they require *two* function applications. For example, here's how to wrap `YourComponent` in a [`DragSource`](/docs-drag-source.html):
 
 -------------------
 ```js
@@ -228,7 +229,7 @@ export default class YourComponent {
 
 ### Putting It All Together
 
-Here is a complete example of wrapping an existing `Card` component into a drag source with some side effects and injecting props into it:
+Below is an example of wrapping an existing `Card` component into a drag source.
 
 -------------------
 ```js
@@ -435,3 +436,4 @@ export default class Card {
 ```
 -------------------
 
+Now you know enough about React DnD to explore the rest of the documentation!

docs/01 Top Level API/DragSource.md

@@ -1,18 +1,21 @@
 DragSource
 ===================
 
-Wrap your component with `DragSource` to make it dragggable.
+Wrap your component with `DragSource` to make it draggable.  
 It is a higher-order component that accepts three required parameters:
 
-* a constant uniquely identifying the kind of data being dragged;
-* a specification object that lets you react to the drag events;
-* a function collecting the props to inject into the draggable component.
+* `type`, a constant uniquely identifying the kind of data being dragged;
+* `spec`, a specification object that lets you react to the drag events;
+* `collect`, a function collecting the props to inject into the draggable component.
 
 They are explored in detail below.
 
+>**Note: This documentation page uses the concepts established in the overview.**  
+>**Please make sure to [read the overview](/docs-overview.html) first.**
+
 ### Signature
 
-`DragSource` uses partial application. After specifying its parameters with the first call, you need to pass your React component class as the only parameter in the second call. This signature makes `DragSource` usable as an ES7 decorator. If this sounds like mumbo jumbo, please refer to the [Overview](/docs-overview.html).
+`DragSource` uses partial application. After specifying its parameters with the first call, you need to pass your React component class as the only parameter in the second call. This signature makes `DragSource` usable as an ES7 decorator. Read the [overview](/docs-overview.html) for a more detailed explanation of the decorators and the higher-order components.
 
 -------------------
 ```js
@@ -41,17 +44,18 @@ import { DragSource } from 'react-dnd';
 @DragSource(type, spec, collect)
 export default class MyComponent {
   /* ... */
-}```
+}
+```
 -------------------
 
 
 ### Parameters
 
-* **`type`**: Required. Either a string, an ES6 symbol, or a function that returns either, given component's `props`. It uniquely identifies the kind of data that this drag source provides. The type is then used to match compatible drag sources and drop targets. You should share a few type constants between the components so they can register sources and targets for the same types of data.
+* **`type`**: Required. Either a string, an ES6 symbol, or a function that returns either, given component's `props`. It uniquely identifies the kind of data that this drag source provides. The type is then used to match compatible drag sources and drop targets. You should share a few type constants between the components so they can register sources and targets for the same types of data. Read the [overview](/docs-overview.html) to get a better idea about types.
 
 * **`spec`**: Required. A plain JavaScript object with a few allowed methods on it. It describes how the drag source reacts to the drag and drop events. See the drag source specification described in detail in the next section.
 
-* **`collect`**: Required. A function. It should return a plain object of the props to inject into your component. It receives two parameters: `connect` and `monitor`. See the example below to learn how to use them to connect the DnD event handlers to React elements and query the current drag state.
+* **`collect`**: Required. The collecting function. It should return a plain object of the props to inject into your component. It receives two parameters: `monitor` and `connect`. Read the [overview](/docs-overview.html) for an introduction to the monitors, the connectors, and the collecting function.
 
 * **`options`**: Optional. A plain object. If some of the props to your component are not scalar (that is, are not primitive values or functions), specifying a custom `arePropsEqual(props, otherProps)` function as an `options` key can improve the performance. Unless you have performance problems, don't worry about it.
 
@@ -73,11 +77,11 @@ The second `spec` parameter must be a plain object implementing the drag source
 
 * **`props`**: Your component's current props.
 
-* **`monitor`**: An instance of [`DragSourceMonitor`](/docs-drag-source-monitor.html). Use it to query the information about the current drag state, such as the currently dragged item and its type, the current and initial coordinates and offsets, and whether it was dropped yet. Refer to the [`DragSourceMonitor` documentation](docs-drag-source-monitor.html) for a complete list of `monitor` methods.
+* **`monitor`**: An instance of [`DragSourceMonitor`](/docs-drag-source-monitor.html). Use it to query the information about the current drag state, such as the currently dragged item and its type, the current and initial coordinates and offsets, and whether it was dropped yet. Read the [`DragSourceMonitor` documentation](docs-drag-source-monitor.html) for a complete list of `monitor` methods, or read the [overview](/docs-overview.html) for an introduction to the monitors.
 
 * **`component`**: When specified, it is the instance of your component. Use it to access the underlying DOM node for position or size measurements, or to call `setState`, and other component methods. It is purposefully missing from `isDragging` and `canDrag` because the instance may not be available by the time they are called. If you want these methods to depend on the component's state, consider lifting the state to the parent component, so that you could just use `props`. Generally your code will be cleaner if you rely on `props` instead whenever possible.
 
-### Writing the `collect` Function
+### The Collecting Function
 
 Just specifying the drag source `type` and `spec` is not quite enough.  
 There's still a few more things we need to take care of:
@@ -87,13 +91,15 @@ There's still a few more things we need to take care of:
 
 All communication between React components happens via props, so it makes sense that React DnD injects special props into your component. However it gives you the freedom to name them and decide what props your component will receive.
 
-In your `collect` function, you receive a `connect` object that lets you connect nodes to the DnD backend you're using, and a `monitor` object to query information about the drag state. You should return a plain object of props to inject into your component from that function.
+Your *collecting function* will be called by React DnD with a *connector* that lets you connect nodes to the DnD backend, and a *monitor* to query information about the drag state. It should return a plain object of props to inject into your component.
+
+If you're new to these concepts, the [overview](/docs-overview.html) should give you a good idea about them.
 
 #### Parameters
 
-* **`connect`**: An instance of [`DragSourceConnector`](/docs-drag-source-connector.html). It has two methods: `dragPreview()` and `dragSource()`. Of them, `dragSource()` is the one you'll use the most. It returns a function you need to pass down to your component to connect the source DOM node to the React DnD backend. If you return something like `{ connectDragSource: connect.dragSource() }` from your `collect` function, the component will receive `connectDragSource` as a prop and can then use it to mark the relevant node inside its `render()` function as draggable: `return this.props.connectDragSource(<div>...</div>)`. You can see this pattern in action in the example at the end of this file. Please refer to the [`DragSourceConnector` documentation](docs-drag-source-connect.html) for more details.
+* **`connect`**: An instance of [`DragSourceConnector`](/docs-drag-source-connector.html). It has two methods: `dragPreview()` and `dragSource()`. Of them, `dragSource()` is the one you'll use the most. It returns a function you need to pass down to your component to connect the source DOM node to the React DnD backend. If you return something like `{ connectDragSource: connect.dragSource() }` from your `collect` function, the component will receive `connectDragSource` as a prop and can then use it to mark the relevant node inside its `render()` function as draggable: `return this.props.connectDragSource(<div>...</div>)`. You can see this pattern in action in the example at the end of this file. Read the [`DragSourceConnector` documentation](docs-drag-source-connector.html) for a complete list of `connect` methods, or read the [overview](/docs-overview.html) for an introduction to the connectors.
 
-* **`monitor`**: An instance of [`DragSourceMonitor`](/docs-drag-source-monitor.html). It is precisely the same `monitor` you receive in the drag source specification methods, and you can use it to query the information about the current drag state. Please refer to the [`DragSourceMonitor` documentation](docs-drag-source-monitor.html) for more details.
+* **`monitor`**: An instance of [`DragSourceMonitor`](/docs-drag-source-monitor.html). It is precisely the same `monitor` you receive in the drag source specification methods, and you can use it to query the information about the current drag state. Read the [`DragSourceMonitor` documentation](docs-drag-source-monitor.html) for a complete list of `monitor` methods, or read the [overview](/docs-overview.html) for an introduction to the monitors.
 
 ### Nesting Behavior
 

site/base.less

@@ -52,6 +52,10 @@ pre, code {
   // letter-spacing: -0.015em;
 }
 
+a code {
+  color: inherit;
+}
+
 code {
   margin: -0.05rem -0.15em;
   padding: 0.05rem 0.35em;