Merge pull request #883 from merriam/master

docs(guide):  Add 'Adding A Page' guide

Author: erikras

README.md

@@ -81,6 +81,7 @@ A demonstration of this app can be seen [running on heroku](https://react-redux.
 * [Exploring the Demo App](docs/ExploringTheDemoApp/ExploringTheDemoApp.md) is a guide that can be used before you install the kit.
 * [Installing the Kit](docs/InstallingTheKit/InstallingTheKit.md) guides you through installation and running the development server locally.
 * [Adding Text to the Home Page](docs/AddingToHomePage/AddingToHomePage.md) guides you through adding "Hello, World!" to the home page.
+* [Adding A Page](docs/AddingAPage/AddingAPage.md) guides you through adding a new page.
 * [React Tutorial - Converting Reflux to Redux](http://engineering.wework.com/process/2015/10/01/react-reflux-to-redux/), by Matt Star
    If you are the kind of person that learns best by following along a tutorial, I can recommend Matt Star's overview and examples.
 

docs/AddingAPage/AddingAPage.md

@@ -0,0 +1,93 @@
+# Adding A Hello Page
+
+This guide adds a `/hello` page to the sample application by 
+following the existing outline.
+
+## Using Ack on About
+
+Searching strings is one way to [grok](https://en.wikipedia.org/wiki/Grok) the structure
+of the kit and sample application.   You can use *grep* or [ack](http://beyondgrep.com) (`brew install ack`).
+I use *ack* with this alias:
+
+![ick Alias](ick_alias.png)
+
+Looking with `ick about` and ignoring documentation, the word *about* appears in these files:
+
+![ick for About](ick_about.png)
+
+## Add the Hello page container
+
+A new page requires new page renderer.  Copy the About page to a 
+new directory and trim out almost all of it:
+
+*  `cd ./src/containers && mkdir ./src/Hello` because each container goes in its own 
+    directory by convention.
+*  `cp About/About.js Hello/Hello.js`
+
+Edit `Hello/Hello.js` into this file:
+
+![New Hello.js](new_hello.png)
+
+
+
+## Edit three files to add Hello
+
+#### Add to `./src/containers/index.js` to include and export the React component:
+
+![Edit index.js](edit_index.png)
+
+#### Add to `./routes.js` to connect the `/hello` url path to the component:
+
+![Edit routes.js 1](edit_route1.png)
+![Edit routes.js 2](edit_route2.png)
+
+#### Add to `./src/containers/App/App.js` to add "Hello" to the NavBar
+
+![Edit App.js](edit_app.png)
+
+And voila, the new 'Hello' page:
+
+![Show Hello](show_hello.png)
+
+# Take-away:  Notice the trade-offs
+
+The task of adding a new page exemplifies two trade-offs in the kit:
+**code versus convention** and the **cut and paste** style.
+
+Convention is a set of constraining rules that automatically trigger
+routine configuration tasks.  For example, WebPack automatically picked up the 
+new directory `./src/containers/Hello` without adding to any configuration files.
+
+On the other hand, routine code was added to `./src/containers/index.js` and 
+`./src/routes.js` to handle the new page.  A convention could automatically
+accomplish the same tasks at either compile or run time.  The cost is new 
+constraints, such as requiring `Hello/Hello.js` to be renamed
+`HelloPage/HelloPage.js`.
+
+Following a style in the code that has no automatic effects is just organic
+growth, not convention.  For example, developers reading `./src/containers/index.js`
+must stop and figure out why all subdirectories except `DevTools` are exported.
+(`DevTools`)[`./src/containers/DevTools/DevTools.js`](https://github.com/erikras/react-redux-universal-hot-example/blob/master/src/containers/DevTools/DevTools.js)
+contains a single function which should be
+[randomly](https://github.com/erikras/react-redux-universal-hot-example/issues/808)
+moved to `./src/utils` or `./src/helpers`.  Using a convention rule that all 
+containers must contain an exported React component would raise an error.
+Organic growth leads to disorder in a project.
+
+Similarly, the **cut and paste** style of coding also degrades the project.
+For example, In `App.js`, the new *NavItem* tag included a new value for the
+*eventkey* property.  The *eventkey*  property is
+[poorly](https://github.com/react-bootstrap/react-bootstrap/issues/320)
+[understood](https://github.com/react-bootstrap/react-bootstrap/issues/432).
+All *eventkey* fields in `App.js` are unused and can be removed.  The 
+**cut and paste** style just compounds an
+[old error](https://github.com/erikras/react-redux-universal-hot-example/commit/d67a79c1e7da5367dc8922019ca726e69d56bf0e)
+and reinforces confusion.
+
+![Edit App revisted](edit_app2.png)
+
+The use of the **cut and paste** style raises well known issues in
+maintenance, documentation, and code quality.  It is not for use in
+production code.  
+
+Some choices about trade-offs are easier than others.