change in the doc structure, added learning objectives, takeaways and… (

uber-archive#7)

* change in the doc structure, added learning objectives, takeaways and further readings

* style touch ups and some minor edits

src/demos/add-charts/style.js

@@ -26,8 +26,7 @@ export const layerControl = {
 
 export const charts = {
   background: 'white',
-  borderRadius: 3,
-  boxShadow: '0 1px 2px rgba(0, 0, 0, 0.1)',
+  border: '1px solid #C0C0C0',
   fontFamily: 'ff-clan-web-pro, "Helvetica Neue", Helvetica, sans-serif !important',
   fontSize: '12px',
   lineHeight: 1.833,

src/demos/introducing-interaction/style.js

@@ -26,8 +26,7 @@ export const layerControl = {
 
 export const charts = {
   background: 'white',
-  borderRadius: 3,
-  boxShadow: '0 1px 2px rgba(0, 0, 0, 0.1)',
+  border: '1px solid #C0C0C0',
   fontFamily: 'ff-clan-web-pro, "Helvetica Neue", Helvetica, sans-serif !important',
   fontSize: '12px',
   lineHeight: 1.833,

src/demos/linking-it-all/style.js

@@ -26,8 +26,7 @@ export const layerControl = {
 
 export const charts = {
   background: 'white',
-  borderRadius: 3,
-  boxShadow: '0 1px 2px rgba(0, 0, 0, 0.1)',
+  border: '1px solid #C0C0C0',
   fontFamily: 'ff-clan-web-pro, "Helvetica Neue", Helvetica, sans-serif !important',
   fontSize: '12px',
   lineHeight: 1.833,

src/docs/deckgl/hexagon-overlay.md

@@ -1,5 +1,10 @@
 <!-- INJECT:"HexagonOverlay" heading -->
 
+<ul class="insert learning-objectives">
+  <li>Discover more types of Deck.GL overlays</li>
+  <li>See how Deck.GL can handle several layers at once</li>
+</ul>
+
 # Add a Hexagon Overlay with Deck.GL
 [View code](https://github.com/uber-common/vis-tutorial/tree/master/demos/hexagon-overlay)
 
@@ -108,7 +113,15 @@ export default class DeckGLOverlay extends Component {
 }
 ```
 
-With this, your `deckgl-overlay.js` should be ready to  render a functional `HexagonLayer`.
+With this, your `deckgl-overlay.js` should be ready to render a functional `HexagonLayer`.
+
+Here's a link to the [complete code of this step](https://github.com/uber-common/vis-tutorial/tree/master/src/demos/hexagon-overlay) 
+
+<ul class="insert takeaways">
+  <li>The HexagonLayer can display aggregated, 3D hexagons</li>
+  <li>Deck.GL can display any number of layers at once</li>
+  <li>It's possible to deactivate any of these layers at run time by replacing it by null</li>
+</ul>
 
 Let's go over some properties of the `HexagonLayer`:
 

src/docs/deckgl/scatterplot-overlay.md

@@ -1,9 +1,11 @@
 <!-- INJECT:"ScatterplotOverlay" heading -->
 
-# Add a Scatterplot Overlay with Deck.GL
+<ul class='insert learning-objectives'>
+<li>Plot data on a map</li>
+<li>First contact with Deck.GL</li>
+</ul>
 
-**NOTE** This step follows from the completed code of the previous section,
-[Starting With A Map](https://uber-common.github.io/vis-tutorial/#/react-map/starting-with-map).
+# Add a Scatterplot Overlay with Deck.GL
 
 As cool as having a map is, an empty map is not that useful. Let's see if we
 can add a `Scatterplot` overlay with the Taxi data set to the map we created in the previous example.
@@ -177,6 +179,21 @@ export default class App extends Component {
 With this, you should have a working `deck.gl` overlay that displays the taxi
 data as a scatterplot overlay.
 
+
+<ul class="insert takeaways">
+  <li>the Deck.GL __DeckGL__ component can be used to plot _layers_ over a map.</li>
+  <li>Each layer can have different parameters that control the result, including a dataset.</li>
+</ul>
+
+<ul class="insert further-readings">
+  <li>[Deck.GL](http://uber.github.io/deck.gl) and its extensive documentation</li>
+  <li>[Gallery of Deck.GL overlays](https://uber-common.github.io/vis-tutorial/#/documentation/data-overlays-gallery/mapping-types)</li>
+</ul>
+
+## Optional section
+
+Feel free to skip to [lesson 3](https://uber-common.github.io/vis-tutorial/#/documentation/3-more-data-overlays-hexagons) or even [lesson 4](https://uber-common.github.io/vis-tutorial/#/documentation/4-a-basic-chart). 
+
 ## 4. Adding Polish
 
 If you check out the source code for this step, you'll see extra code that add
@@ -185,8 +202,9 @@ loading spinner.
 
 The control for the settings panel is already provided in your starting code. It's a typical React component, so there's no use going through the details in this tutorial. 
 
+## 5. code of app.js
 
-Here's the complete app.js file including the control panel: 
+Here's the complete [app.js](https://github.com/uber-common/vis-tutorial/blob/master/src/demos/scatterplot-overlay/app.js) file including the control panel: 
 
 ```js
 /* global window */

src/docs/react-vis/basic.md

@@ -1,5 +1,9 @@
 <!-- INJECT:"AddCharts" heading -->
 
+<ul class="insert learning-objectives">
+  <li>Create a simple chart</li>
+</ul>
+
 # Adding Charts with React-Vis
 
 [React-Vis](http://uber.github.io/react-vis) is the Uber library for rendering charts with React.
@@ -11,7 +15,6 @@ In React Vis, creating a chart has a nice React-y feeling of assembling componen
 We're going to need extra data for the charts.
 
 in your app.js file, change your _processData method by this one: 
-
 ```js
   _processData() {
     if (taxiData) {
@@ -216,9 +219,23 @@ We could actually pass a yDomain prop in the YAxis and the VerticalBarSeries com
 
 To read more about axes in React-Vis, consult the [Axes docs](https://uber.github.io/react-vis/documentation/api-reference/axes).
 
-## 3. Fine tune our chart
+<ul class="insert takeaways">
+  <li>With the React-Vis component __XYPlot__ you can insert charts in your application.</li>
+  <li>And again, these charts work like other React components - with props and callbacks.</li>
+  <li>XYPlot can have various children like XAxis or BarSeries.</li>
+  <li>Series-type components need to have a _data_ prop.</li>
+</ul>
+
+<ul class="insert further-readings">
+  <li>[Visualization guidelines](https://uber-common.github.io/vis-tutorial/#documentation/visualization-guidelines/do-clear-simple-charts) - beyond technique, advice on how to build meaningful charts</li>
+  <li>[React-Vis](https://uber.github.io/react-vis/) and its documentation</li>
+</ul>
 
-**For the rest of the tutorial, you can now jump to the next section.**
+## Optional section
+
+Feel free to skip to [lesson 5](https://uber-common.github.io/vis-tutorial/#/documentation/5-interactions)
+
+## 3. Fine tune our chart
 
 The rest of this document will guide you through further fine-tuning improvements we can do to our chart, as the difference between a good chart and a great chart lie in the details.
 
@@ -296,6 +313,8 @@ React-Vis has a many forms available for your charts. Here we're going to use Li
 
 To learn about various React-Vis series, checkout [their docs](https://uber.github.io/react-vis/documentation/series-reference/arc-series).
 
+Here's a link to the [complete code of this step](https://github.com/uber-common/vis-tutorial/tree/master/src/demos/add-charts)
+
 Final charts.js code:
 
 ```js

src/docs/react-vis/interactions.md

@@ -1,5 +1,9 @@
 <!-- INJECT:"IntroducingInteraction" heading -->
 
+<ul class="insert learning-objectives">
+  <li>Implement mouse interactions in a chart</li>
+</ul>
+
 # Introducing interaction
 
 ## 1. Interact with bar charts on hover
@@ -143,3 +147,15 @@ And in the VerticalBarSeries component:
 We can change the style of the cursor to pointer by passing a style property, that's a nice way to signal that an element is clickable.
 
 If the user clicks on a bar twice, it will be unselected.
+
+<ul class="insert takeaways">
+  <li>XYPlot and Series components can take callbacks as props to handle mouse events</li>
+</ul>
+
+<ul class="insert further-readings">
+  <li>
+    [React-Vis interaction documentation](https://uber.github.io/react-vis/documentation/general-principles/interaction)
+  </li>
+</ul>
+
+Here's a link to the [complete code of this step](https://github.com/uber-common/vis-tutorial/tree/master/src/demos/introducing-interaction)

src/docs/react-vis/linking-it-all.md

@@ -1,4 +1,7 @@
 <!-- INJECT:"LinkingItAll" heading -->
+<ul class="insert learning-objectives">
+  <li>Enable our chart to interact with our data overlays</li>
+</ul>
 
 # Linking it all
 
@@ -67,6 +70,13 @@ const layers = [
 
 And as you can see, interactions on the bar chart are now visible on our deck.gl part!
 
+<ul class="insert takeaways">
+  <li>React-Vis and Deck.GL components can interact with each other and their parent, just like any other React component!</li>
+  <li>There's no limit to what you can achieve!</li>
+</ul>
+
+Here's a link to the [complete code of this step](https://github.com/uber-common/vis-tutorial/tree/master/src/demos/linking-it-all)
+
 # Congratulations!
 
 You've built your own interactive mapping application combining Mapbox-powered maps in react, WebGL layers and versatile charts!

src/docs/setup.md

@@ -32,7 +32,17 @@ Note that the repository you cloned also contains all the content and code of th
 
 In the pages of this tutorial, you can use the back quote key ` (typically located below ESC) to see the code examples in full page.
 
-## 3. Start Coding!
+## 3. How this tutorial works
+
+In this tutorial, you will build a full geospatial application from scratch, with maps, WebGL data overlays and interactive charts. 
+
+In each lesson, we'll highlight what we'll cover, then we'll go through the code examples - copying the examples is how we'll build the app step by step. Some parts of the lessons are skippable - you can move to the next session and still have a functional app at the end. 
+
+Feel free to explore and experiment as you copy the code examples, you can find working code that correspond to the start of each lesson in the repository.
+
+We'll end each lesson with key takeaways and further reading.
+
+## 4. Start Coding!
 
 You can now open your text editor with the following file:
 

src/docs/starting-with-map.md

@@ -1,5 +1,10 @@
 <!-- INJECT:"StartingWithMap" heading -->
 
+<ul class='insert learning-objectives'>
+<li>Create a map in a React application,</li>
+<li>Add interaction to the map (zoom, pan, resize window)</li>
+</ul>
+
 # Starting With a Map
 
 [react-map-gl](https://github.com/uber/react-map-gl) is a `React` wrapper around
@@ -162,9 +167,17 @@ export default class App extends Component {
 We leverage the `onViewportChange` callback to make sure there's only one place
 where viewport state is actually being updated.
 
+<ul class='insert takeaways'>
+<li>We can use the ReactMapGL's MapGL component to use a map in React.</li>
+<li>MapGL behaves just as another React component with props and callbacks.</li>
+<li>Basic settings of the map are stored in the __viewport__ prop.</li>
+<li>the __onViewportChange__ prop can be used to update the viewport when a user interacts with the map.</li>
+</ul>
+
 ## 6. Completed Code
 
-Our completed component should now look like this:
+Our completed component [app.js](https://github.com/uber-common/vis-tutorial/blob/master/src/demos/starting-with-map/app.js) should now look like this:
+
 ```js
 /* global window */
 import React, {Component} from 'react';

src/mdRoutes.js

@@ -21,65 +21,66 @@ import confusing from 'docs/guidelines/axes.md';
 export default [{
   name: 'Documentation',
   path: '/documentation',
-  data: [{
-    name: 'Setup',
-    markdown: setup,
-  }, {
-    name: 'React Map Gl',
-    children: [{
-      name: 'Starting with a Map',
-      markdown: startingMap,
-    }],
-  }, {
-    name: 'Mapping Guidelines',
-    children: [{
-      name: 'Mapping types',
-      markdown: mappingSimple,
+  data: [
+    {
+      name: 'Setup',
+      markdown: setup
+    },
+    {
+      name: '1. Starting with a Map',
+      markdown: startingMap
+    },
+    {
+      name: '2. Map data overlays - scatterplot',
+      markdown: deckScatterplot
+    },
+    {
+      name: '3. More data overlays - hexagons',
+      markdown: deckHexagon
+    },
+    {
+      name: '4. A basic chart',
+      markdown: basicCharts
+    },
+    {
+      name: '5. Interacting with charts',
+      markdown: interactions
+    },
+    {
+      name: '6. Linking if all',
+      markdown: linkingAll
+    }, 
+    {
+      name: 'Data overlays gallery',
+      children: [{
+        name: 'Mapping types',
+        markdown: mappingSimple,
+      }, {
+        name: 'Scatterplot',
+        markdown: mappingScatterplot,
+      }, {
+        name: 'Arc',
+        markdown: mappingArc,
+      }, {
+        name: 'Hexagon',
+        markdown: mappingHexagon,
+      }]
     }, {
-      name: 'Scatterplot',
-      markdown: mappingScatterplot,
-    }, {
-      name: 'Arc',
-      markdown: mappingArc,
-    }, {
-      name: 'Hexagon',
-      markdown: mappingHexagon,
-    }]
-  }, {
-    name: 'Deck GL',
-    children: [{
-      name: 'Scatterplot Overlay',
-      markdown: deckScatterplot,
-    }, {
-      name: 'Hexagon Overlay',
-      markdown: deckHexagon,
-    }],
-  }, {
-    name: 'React Vis',
-    children: [{
-      name: 'Basic Charts',
-      markdown: basicCharts,
-    }, {
-      name: 'Interactions',
-      markdown: interactions,
-    }, {
-      name: 'Linking It All',
-      markdown: linkingAll,
-    }],
-  }, {
-    name: 'Visualization Guidelines',
-    children: [{
-      name: 'Do: Clear simple charts',
-      markdown: simpleCharts,
-    }, {
-      name: 'Do: Use hierarchy',
-      markdown: hierarchy,
-    }, {
-      name: 'Don\'t: Too much to see',
-      markdown: tooMuch,
-    }, {
-      name: 'Don\'t: Confusing axes',
-      markdown: confusing,
-    }],
-  }],
-}]
+      name: 'Visualization Guidelines',
+      children: [{
+        name: 'Do: Clear simple charts',
+        markdown: simpleCharts,
+      }, {
+        name: 'Do: Use hierarchy',
+        markdown: hierarchy,
+      }, {
+        name: 'Don\'t: Too much to see',
+        markdown: tooMuch,
+      }, {
+        name: 'Don\'t: Confusing axes',
+        markdown: confusing,
+      }]
+    }
+  ]
+}];
+