Improve Initial Docs Experience

packages/react-router-dom/docs/guides/quick-start.md

@@ -1,9 +1,10 @@
 # Quick Start
 
-The easiest way to get started with a React web project is with a tool called [Create React App][crapp], a Facebook project with a ton of community help.
+You'll need a React web app to add `react-router`.
 
-First install create-react-app if you don't already have it, and then
-make a new project with it.
+If you need to create one, the easiest way to get started is with a popular tool called [Create React App][crapp].
+
+First install `create-react-app`, if you don't already have it, and then make a new project with it.
 
 ```sh
 npm install -g create-react-app
@@ -13,46 +14,83 @@ cd demo-app
 
 ## Installation
 
-React Router DOM is [published to npm](https://npm.im/react-router-dom) so you can install it with either `npm` or [`yarn`](https://yarnpkg.com). Create React App uses yarn, so that's what we'll use.
+React Router DOM is [published to npm](https://npm.im/react-router-dom) so you can install it with either `npm` or [`yarn`](https://yarnpkg.com).
 
 ```sh
-yarn add react-router-dom
-# or, if you're not using yarn
 npm install react-router-dom
 ```
 
-Now you can copy/paste any of the examples into `src/App.js`. Here's the
-basic one:
+Copy/paste either of the examples (below) into your `src/App.js`.
+
+## Example: Basic Routing
+
+In this example we have 3 'Page' Components handled by the `<Router>`.
+
+Note: Instead of `<a href="/">` we use `<Link to="/">`.
 
 ```jsx
 import React from "react";
 import { BrowserRouter as Router, Route, Link } from "react-router-dom";
 
-const Home = () => (
-  <div>
-    <h2>Home</h2>
-  </div>
-);
+const Index = () => <h2>Home</h2>;
+const About = () => <h2>About</h2>;
+const Users = () => <h2>Users</h2>;
 
-const About = () => (
-  <div>
-    <h2>About</h2>
-  </div>
+const AppRouter = () => (
+  <Router>
+    <div>
+      <nav>
+        <ul>
+          <li>
+            <Link to="/">Home</Link>
+          </li>
+          <li>
+            <Link to="/about/">About</Link>
+          </li>
+          <li>
+            <Link to="/users/">Users</Link>
+          </li>
+        </ul>
+      </nav>
+
+      <Route path="/" exact component={Index} />
+      <Route path="/about/" component={About} />
+      <Route path="/users/" component={Users} />
+    </div>
+  </Router>
 );
 
-const Topic = ({ match }) => (
-  <div>
-    <h3>{match.params.topicId}</h3>
-  </div>
+export default AppRouter;
+```
+
+## Example: Nested Routing
+
+This example shows how nested routing works. The route `/topics` loads the `Topics` component, which renders any further `<Route>`'s conditionally on the paths `:id` value.
+
+```jsx
+import React from "react";
+import { BrowserRouter as Router, Route, Link } from "react-router-dom";
+
+const App = () => (
+  <Router>
+    <div>
+      <Header />
+
+      <Route exact path="/" component={Home} />
+      <Route path="/about" component={About} />
+      <Route path="/topics" component={Topics} />
+    </div>
+  </Router>
 );
 
+const Home = () => <h2>Home</h2>;
+const About = () => <h2>About</h2>;
+const Topic = ({ match }) => <h3>Requested Param: {match.params.id}</h3>;
 const Topics = ({ match }) => (
   <div>
     <h2>Topics</h2>
+
     <ul>
-      <li>
-        <Link to={`${match.url}/rendering`}>Rendering with React</Link>
-      </li>
       <li>
         <Link to={`${match.url}/components`}>Components</Link>
       </li>
@@ -61,39 +99,29 @@ const Topics = ({ match }) => (
       </li>
     </ul>
 
-    <Route path={`${match.path}/:topicId`} component={Topic} />
+    <Route path={`${match.path}/:id`} component={Topic} />
     <Route
       exact
       path={match.path}
       render={() => <h3>Please select a topic.</h3>}
     />
   </div>
 );
-
-const BasicExample = () => (
-  <Router>
-    <div>
-      <ul>
-        <li>
-          <Link to="/">Home</Link>
-        </li>
-        <li>
-          <Link to="/about">About</Link>
-        </li>
-        <li>
-          <Link to="/topics">Topics</Link>
-        </li>
-      </ul>
-
-      <hr />
-
-      <Route exact path="/" component={Home} />
-      <Route path="/about" component={About} />
-      <Route path="/topics" component={Topics} />
-    </div>
-  </Router>
+const Header = () => (
+  <ul>
+    <li>
+      <Link to="/">Home</Link>
+    </li>
+    <li>
+      <Link to="/about">About</Link>
+    </li>
+    <li>
+      <Link to="/topics">Topics</Link>
+    </li>
+  </ul>
 );
-export default BasicExample;
+
+export default App;
 ```
 
 Now you're ready to tinker. Happy routing!

packages/react-router/docs/guides/philosophy.md

@@ -7,6 +7,7 @@ This guide's purpose is to explain the mental model to have when using React Rou
 If you've used Rails, Express, Ember, Angular etc. you've used static routing. In these frameworks, you declare your routes as part of your app's initialization before any rendering takes place. React Router pre-v4 was also static (mostly). Let's take a look at how to configure routes in express:
 
 ```js
+// Express Style routing:
 app.get("/", handleIndex);
 app.get("/invoices", handleInvoices);
 app.get("/invoices/:id", handleInvoice);
@@ -18,6 +19,7 @@ app.listen();
 Note how the routes are declared before the app listens. The client side routers we've used are similar. In Angular you declare your routes up front and then import them to the top-level `AppModule` before rendering:
 
 ```js
+// Angular Style routing:
 const appRoutes: Routes = [
   {
     path: "crisis-center",
@@ -54,6 +56,7 @@ imports into the application for you. Again, this happens before
 your app renders.
 
 ```js
+// Ember Style Router:
 Router.map(function() {
   this.route("about");
   this.route("contact");

website/modules/docs/Native.js

@@ -79,10 +79,10 @@ export default {
     }
   ],
   guides: [
-    require("../../../packages/react-router/docs/guides/philosophy.md"),
     require("../../../packages/react-router-native/docs/guides/quick-start.md"),
     require("../../../packages/react-router-native/docs/guides/deep-linking.md"),
     require("../../../packages/react-router-native/docs/guides/animation.md"),
+    require("../../../packages/react-router/docs/guides/philosophy.md"),
     require("../../../packages/react-router/docs/guides/redux.md"),
     require("../../../packages/react-router/docs/guides/blocked-updates.md")
   ]

website/modules/docs/Web.js

@@ -19,12 +19,12 @@ export default {
   ],
 
   guides: [
-    require("../../../packages/react-router/docs/guides/philosophy.md"),
-    require("../../../packages/react-router-dom/docs/guides/basic-components.md"),
     require("../../../packages/react-router-dom/docs/guides/quick-start.md"),
+    require("../../../packages/react-router-dom/docs/guides/basic-components.md"),
     require("../../../packages/react-router-dom/docs/guides/server-rendering.md"),
     require("../../../packages/react-router-dom/docs/guides/code-splitting.md"),
     require("../../../packages/react-router-dom/docs/guides/scroll-restoration.md"),
+    require("../../../packages/react-router/docs/guides/philosophy.md"),
     require("../../../packages/react-router/docs/guides/testing.md?web"),
     require("../../../packages/react-router/docs/guides/redux.md"),
     require("../../../packages/react-router/docs/guides/static-routes.md"),