Reduce React emphasisis in docs. Miminize top README, add congributin…

…g.md (visgl#1851)
mpearson · May 23, 2018 · 1084ba2 · 1084ba2
1 parent 8ef5dae
commit 1084ba2
Show file tree

Hide file tree

Showing 9 changed files with 113 additions and 163 deletions.
diff --git a/README.md b/README.md
@@ -18,79 +18,49 @@
 
 <h1 align="center">deck.gl | <a href="https://uber.github.io/deck.gl">Docs</a></h1>
 
-<h5 align="center">A WebGL overlay suite for React providing a set of highly performant data visualization overlays</h5>
+<h5 align="center">A suite of WebGL2-powered data visualization layers</h5>
 
 [![docs](http://i.imgur.com/mvfvgf0.jpg)](https://uber.github.io/deck.gl)
 
-Provides tested, highly performant layers for data visualization,
-such as scatterplots, arcs, geometries defined in GeoJSON, etc...
+Provides tested, highly performant layers for data visualization, such as scatterplots, arcs, geometries defined in GeoJSON, etc.
+
+deck.gl has extensive documentation, please refer to the [docs website](https://uber.github.io/deck.gl) or browse it directly in the github [docs folder](./docs).
 
-    npm install --save deck.gl
 
 ## Using deck.gl
 
-To learn how to use deck.gl through examples coming with the deck.gl repo,
-please clone the latest **release** branch.
+deck.gl can be used through its standard JavaScript API (available both as installable npm modules as well as a "script" file for use in scripting setups). However, if you are using React you will likely want to use the provided React integration. Again, consult the extensive documentation for more details on how to access what you need.
+
 
-`git clone -b 5.1-release --single-branch https://github.com/uber/deck.gl.git`
+## Examples
 
-A very simple usage of deck.gl is showcased in the [hello-world examples](./examples),
-using both [webpack2](./examples/hello-world-webpack2) and
-[browserify](./examples/hello-world-browserify),
-so you can choose which setup you prefer or are more familiar with.
+To get a quick feel for deck.gl applicaiton source code might look like, say the application has some data representing flights with start and end positions for each item. If it wanted to display this data as a set of arcs it would simply import and render a deck.gl `ArcLayer`:
 
 ```javascript
 import DeckGL, {ArcLayer} from 'deck.gl';
 
 const flights = new ArcLayer({
-  id: 'flights',
-  data: [] // Some flight points
+  data: [] // Some flight points,
+  ...
 });
 
 <DeckGL width={1920} height={1080} layers={[flights]} />
 ```
 
-You can also take a look at the [docs website](https://uber.github.io/deck.gl)
-or browse directly the [docs folder](./docs).
-
-## Developing deck.gl
-
-The **master** branch is the active development branch.
-
-    npm run bootstrap
-    npm test
-    npm start  # See note below
-
-Note that `npm start` in the main directory actually runs `examples/layer-browser`.
-
+Simple usage of deck.gl is also showcased in the [hello-world examples](./examples/get-started), using both [webpack2](./examples/get-started/hello-world-webpack2) and [browserify](./examples/get-started/hello-world-browserify), so you can choose which bundler you prefer or are more familiar with.
 
-#### Node Version Requirement
+To learn how to use deck.gl through the many examples that coming with the deck.gl repo, please clone the latest **release** branch. `git clone -b 5.3-release --single-branch https://github.com/uber/deck.gl.git`
 
-Running deck.gl as a dependency in another project (e.g. via `npm i deck.gl`) requires Node `4.x` or higher.
-Building deck.gl from source has a dependency on Node `8.x` or higher.
-Either upgrade to a supported version, or install something like
-[nvm](https://github.com/creationix/nvm) to manage Node versions.
+For the most up-to-date information, see our [docs](http://uber.github.io/deck.gl/#/docs/getting-started/installation?section=running-the-examples)
 
-#### Install yarn
-On macOS deck.gl uses [yarn](https://www.npmjs.com/package/yarn) to manage packages.
-To develop deck.gl, [install yarn](https://yarnpkg.com/en/docs/install) with brew
-
-```
-brew update
-brew install yarn
-
-```
 
 ## Contributing
 
-PRs and bug reports are welcome. Note that you once your PR is
-about to be merged, you will be asked to register as a contributor
-by filling in a short form.
+PRs and bug reports are welcome, and we are actively opening up the deck.gl roadmap to facilitate for external contributors.
 
-## Data sources
+Note that you once your PR is about to be merged, you will be asked to register as a contributor by filling in a short form.
 
-[SF OpenData](https://data.sfgov.org)
 
-[TLC Trip Record Data](http://www.nyc.gov/html/tlc/html/about/trip_record_data.shtml)
+## Data sources
 
-[Mapzen](https://mapzen.com/)
+Data sources are listed in each example.
diff --git a/docs/README.md b/docs/README.md
@@ -48,20 +48,26 @@ deck.gl has been developed in parallel with a number of companion modules, e.g.:
 
 How you approach learning deck.gl will depend on your previous knowledge and how you want to use it.
 
-Learning the layer props, and reading the basic articles in the deck.gl documentation should of course be the first step. But where to go after that?
+Getting familiar with the various layers and their props, and reading the basic articles in the deck.gl developer guide should of course be one of the first steps.
 
-### Understanding the Reactive Programming Model
+Exploring the deck.gl examples is a good starting point.
 
-deck.gl is designed according to the principles of the [Reactive Programming Model](https://en.wikipedia.org/wiki/Reactive_programming).
+In-depth tutorials for how to develop deck.gl applications are available on the [Vis Academy](http://vis.academy/#/) website.
 
-The key to writing good, performant deck.gl applications and layers lies in understanding how to minimize updates and redundant calculations.
+And our [blog](https://medium.com/vis-gl) contains a lot of additional information that might be helpful.
 
-It is important to understand the implications of the shallow equality comparisons deck.gl performs on layer properties, and how this implies that new data and property objects must only be created when the underlying data actually changes in order to prevent unnecessary updates.
+But where to go after that?
+
+
+### Learning Reactive UI Programming
+
+deck.gl is designed according to functional UI programming principles, made fashionable by frameworks like React. The key to writing good, performant deck.gl applications and layers lies in knowing how to minimize updates and redundant calculations, understanding concepts like "shallow equality" etc. This is critical when using deck.gl with React, but can still be helpful to understand when using deck.gl in non-React contexts.
+
+There is an impressive amount of information (documentation, blog posts, educational videos, etc.) on the reactive programming paradigm in relation to modern web frameworks such as React, Flux and Redux. Where to start depends mostly on your application architecture choices. Exploring such information will take you beyond what we can cover in the basic deck.gl developer guide article on Updates.
 
-There is an impressive amount of information (documentation, blog posts, educational videos, etc.) on the reactive programming paradigm in relation to modern web frameworks such as React, Flux and Redux. Where to start depends mostly on your application architecture choices.
 
 ### Understanding WebGL
 
-This is only needed if you want to create custom layers in deck.gl. Note that while trying out a new ambitious rendering approach for a new layer will likely require deeper knowledge, it is often possible to modify or extend existing deck.gl layers (including modifying the shader code) with a surprisingly limited amount of WebGL knowledge.
+Knowledge of WebGL is only needed if you want to create custom layers in deck.gl. Note that while trying out a new ambitious rendering approach for a new layer will likely require deeper knowledge, it is often possible to modify or extend existing deck.gl layers (including modifying the shader code) with a surprisingly limited amount of WebGL knowledge.
 
 There are many web resources for learning WebGL. [luma.gl](https://uber.github.io/luma.gl/#/) can be a good start.
diff --git a/docs/api-reference/layer.md b/docs/api-reference/layer.md
@@ -44,7 +44,7 @@ The `id` must be unique among all your layers at a given time. The default value
 
 Remarks:
 
-* `id` is similar to the `key` property used in React to match components between rendering calls, with the difference that deck.gl requires each layer to have a unique `id` whereas in React the `key` is optional but recommended.
+* `id` is used to match layers between rendering calls. deck.gl requires each layer to have a unique `id`. A default `id` is assigned based on layer type, which means if you are using more than one layer of the same type (e.g. two `ScatterplotLayer`s) you need to provide a custom `id` for at least one of them.
 * A layer's name is defined by the `Layer.layerName` static member, or inferred from the constructor name (which is not robust in minified code).
 * For sublayers (automatically generated by composite layers), a unique "composite layer id" is automatically generated by appending the sub layer's id to the parent layer's `id`, so there is no risk of `id` collisions for sublayers, as long as the application's layer names are unique.
 
@@ -230,7 +230,7 @@ Note:
 
 The `parameters` allows applications to specify values for WebGL parameters such as blending mode, depth testing etc. Any `parameters` will be applied temporarily while rendering this layer only.
 
-Please refer to the luma.gl v4 [setParameters](http://uber.github.io/luma.gl/#/documentation/api-reference/get-parameter) API for documentation on supported parameters and values.
+Please refer to the luma.gl [setParameters](http://uber.github.io/luma.gl/#/documentation/api-reference/get-parameter) API for documentation on supported parameters and values.
 
 
 ##### `getPolygonOffset` (Function, optional)

diff --git a/docs/api-reference/web-mercator-viewport.md b/docs/api-reference/web-mercator-viewport.md
@@ -8,7 +8,7 @@ For more information consult the [Viewports](/docs/developer-guide/viewports.md)
 
 ## Usage
 
-The `WebMercatorViewport` is the default viewport for deck.gl. If you are using the `DeckGL` React component you may not even need to instantiate it explicitly.
+The `WebMercatorViewport` is the default viewport for deck.gl, created under the hood to do geospatial projections in JavaScript.
 
 ```jsx
 import DeckGL from 'deck.gl';

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,44 @@
+# Contributing
+
+PRs and bug reports are welcome, and we are actively opening up the deck.gl roadmap to facilitate for external contributors.
+
+
+## Practicalities
+
+Note that you once your PR is about to be merged, you will be asked to register as a contributor by filling in a short form.
+
+
+## Developer documentation
+
+Developer documentaion is available [here](https://github.com/uber/deck.gl/tree/master/dev-docs). We are ready to prepare additional documentation if requested by contributors.
+
+
+## Developing deck.gl
+
+The **master** branch is the active development branch.
+
+```bash
+npm run bootstrap
+npm test
+npm start  # See note below
+```
+
+Note that `npm start` in the main directory actually runs `examples/layer-browser`.
+
+
+### Node Version Requirement
+
+Running deck.gl as a dependency in another project (e.g. via `npm i deck.gl`) requires Node `4.x` or higher. Building deck.gl from source has a dependency on Node `8.x` or higher. Either upgrade to a supported version, or install something like [nvm](https://github.com/creationix/nvm) to manage Node versions.
+
+
+### Install yarn
+
+We use [yarn](https://yarnpkg.com/en/docs/install) to manage packages to install deck.gl
+
+Note: on MacOS it is often convenient to install yarn with brew
+
+```bash
+brew update
+brew install yarn
+
+```