First batch of doc updates (#1073)

docs/README.md

@@ -36,10 +36,10 @@ These docs are for
 
 ## Philosophy
 
-Like most frameworks, luma.gl has been developed with a certain philosophy in mind, reflecting things its designers feel to be important to their work.
+luma.gl's core philosophy is to expose the WebGL 2 API to developers, while providing fallbacks to WebGL 1 when necessary. The core use case for luma.gl is visualization of large datasets, but its design is generic enough for more general usage. Key aspects of that philosphy are:
 
 - **A WebGL2-first API** - luma.gl enables applications to code using the latest WebGL2 APIs and write their shaders in the latest GLSL 3.00 ES syntax, and (as far as possible) transparently keeps your application backwards compatible with WebGL1 (using WebGL extensions, shader transpilation and other techniques).
-- **Expose WebGL2 to Programmers** - while many WebGL frameworks make efforts to hide and wrap the WebGL2 API, luma.gl intentionally exposes it, providing JavaScript classes corresponding to all WebGL objects defined in the [WebGL2 Specification](https://www.khronos.org/registry/webgl/specs/latest/2.0/).
+- **Expose WebGL2 to Programmers** - while many WebGL frameworks make efforts to hide and wrap the WebGL2 API, luma.gl intentionally exposes it, providing JavaScript classes corresponding to WebGL objects defined in the [WebGL2 Specification](https://www.khronos.org/registry/webgl/specs/latest/2.0/).
 - **Simplify use of the WebGL2 API** - Using the raw WebGL API is notoriously verbose and fiddly. luma.gl's classes provide the standard WebGL2 objects and methods, but take care of all the tedious default parameters and object bindings behind the scenes.
 - **Shader Programming** - luma.gl's shadertools is a GLSL module system that provides extensive facilities for developing, modularizing, debugging and profiling GLSL shaders.
 - **Performance First** - luma.gl has strong focus on performance, which includes a preference for providing APIs on lower abstraction levels than some popular WebGL frameworks, and an emphasis of using features such as *instanced rendering* for large data sets.
@@ -48,39 +48,30 @@ Like most frameworks, luma.gl has been developed with a certain philosophy in mi
 
 ## History
 
-luma.gl was originally created in late 2015 as a fork of [PhiloGL](https://github.com/philogb/philogl) to provide high performance WebGL rendering capability for [deck.gl](https://github.com/uber/deck.gl) - a 3D visualization framework for large scale data.
+luma.gl was originally created in late 2015 as a fork of [PhiloGL](https://github.com/philogb/philogl) to provide high performance WebGL rendering capability for [deck.gl](https://github.com/uber/deck.gl) - a 3D visualization framework for large scale data. As deck.gl became increasingly popluar, luma.gl saw heavier usage.
 
-With the increased adoption of the deck.gl framework, usage of luma.gl has also gradually increased. In addition, various contributors have started to create up their own custom deck.gl layers for their apps, which requires usage of luma.gl's classes and APIs. This triggered a major rewrite the documentation and the website.
+WebGL 2 introduced several powerful features related to general purpose GPU usage (GPGPU) and reducing driver overhead for drawing massive numbers of objects, both of significant interest in the domain of geospatial visualization. luma.gl is built to expose these new features, while providing polyfills wherever possible when falling back to WebGL 1.
 
-The arrival of WebGL2 was a major milestone in the WebGL landscape. With the release of luma.gl v4 in July 2017, luma.gl was positioned as a foundation library for high-performance GPU programming in JavaScript, and luma.gl v5 and v6 series releases have continued to provide incremental improvements in the WebGL2 and GPGPU areas.
-
-Today, luma.gl is the foundational WebGL library in the vis.gl framework suite, but is designed so that it can be used stand-alone.
+Today, luma.gl is the core 3D rendering library in the [vis.gl](http://vis.gl/) framework suite.
 
 
 ## Comparison with other WebGL frameworks
 
-luma.gl is the natural choice if you are working with any of the WebGL-based frameworks in the vis.gl suite (deck.gl, kepler.gl etc).
-
-If not, and you are considering what WebGL framework to use in an independent project, then as a first step towards a decision we recommend that you take a look at the things that have been built on luma.gl (e.g. vis.gl), make sure the luma.gl design philosophy resonates with you, and finally, review the luma.gl roadmap to see that the library is heading in a direction that is meaningful to you.
-
-We think that luma.gl could be a great choice if:
-
-* you want to work with, learn, and leverage the power of the WebGL2 API.
-* you want "more control" by having the option of working close to WebGL.
-* you want to do shader coding
-* you are focusing on rendering large data sets with high performance.
+luma.gl is a strong choice if the following are priorities:
+ * Low-level access to WebGL 2 constructs: programs, shaders, buffers, etc.
+ * Access to the WebGL 2 API, with seamless fallbacks to WebGL 1 for functionality that can be polyfilled via, for example, WebGL 1 extensions.
+ * A focus on drawing large number of objects with minimal overhead.
 
-We feel that luma.gl is currently not the strongest choice if:
+Note, however that luma.gl is not a complete game engine or scenegraph library, as its priority is to provide low-level access to the GPU. There is some support for higher-level abstractions like a `Model` class and a scenegraph, but these are relatively thin layers over core WebGL constructs.
 
-* You wish to avoid learning anything about WebGL, working exclusively with higher abstractions.
-* You need to load 3D models from various formats.
-* You need traditional game engine support for scenegraphs, complex materials, advanced lighting options, etc.
-
-If you are considering luma.gl because you are interested in using WebGL2 and you are looking for options, it is worth noting that some of the more mature WebGL frameworks have been rather slow to upgrade to WebGL2, either because of historical reasons (e.g. existing higher-level APIs do not provide an obvious upgrade path) or for philosophical reasons (e.g. maintainers feel that WebGL2 is not worthwhile for their particular use cases).
-
-If you are interested in using luma.gl with a higher abstraction level API, or just see what can be achieved with luma.gl, take a look at deck.gl and kepler.gl.
+For some powerful examples of what can be achieved with luma.gl, take a look at [deck.gl](http://deck.gl/#/), [kepler.gl](https://kepler.gl/) and [avs.auto](https://avs.auto/#/).
 
 
 ## Future
 
-The current development direction for luma.gl can be found in the roadmap page on our website.
+We share information about the direction of luma.gl in the following ways:
+
+* **[RFCs](https://github.com/uber/luma.gl/tree/master/dev-docs/RFCs)** - RFCs are technical writeups that describe proposed features in upcoming releases.
+* **[Roadmap Document](https://luma.gl/#/documentation/overview/roadmap)** - (this document) A high-level summary of our current direction for future releases.
+* **[Blog](https://medium.com/@vis.gl)** - We use the vis.gl blog to share information about what we are doing.
+* **[Github Issues](https://github.com/uber/luma.gl/issues)** - The traditional way to start or join a discussion.

docs/developer-guide/README.md

@@ -1,9 +1,31 @@
-# Developer Guide
+# Development Environment
 
-Welcome to the luma.gl developer guide.
+To get started developing luma.gl, first make sure to install all dependancies from the repository root:
 
+`yarn bootstrap`
 
-## Additional Information Sources
+luma.gl's source code is in the `modules/` directory. Development is most easily done by running the examples in development mode, e.g.:
 
-* [WebGL2 Fundamentals](https://webgl2fundamentals.org/) - luma.gl is essentially a set of WebGL2 components, so the more you know about WebGL2 the better. This site is a great place to start reading.
-* [WebGL Insights](http://webglinsights.com/) - This classic WebGL book is now available as a free PDF download!
+```
+cd examples/core/instancing
+yarn
+yarn start-local
+```
+
+Any modifications made to the source or example code will cause the example to rebuild and the page to refresh, making quick iterations on code changes straightforward.
+
+Testing against the full website can be done by running `yarn start` in the the `website/`. This full website take longer to build but makes it easier to test against all examples. This can be helpful when making core changes to luma.gl. As with running the examples in development mode, a rebuild and page refresh will be triggered whenever source or website code is updated.
+
+
+## Testing
+
+Testing is performed on Travis CI and using a precommit hook. Local testing is supported on these environments:
+
+* `yarn test` - runs tests under node using headless.gl and a headless Chrome instance (using [SwiftShader](https://github.com/google/swiftshader)).
+* `yarn test browser` - Tests in your browser, may be helpful to quickly debug test case failures since it autoreloads on changes and gives you full access to your browser's debugger.
+
+When adding new features, please add relevant unit tests to the `test/` directory in the relevant module.
+
+### Helpful Hints
+- To only run one test from the suite for debugging purposes, change a call to `test` in the relevant spec to `test.only`. Remember to change this back before committing!
+- If a test fails in `headless`, but not in the browser, it's likely due to a difference in the contexts created (WebGL 1 versus 2), or the extensions available. Running in a browser without WebGL 2 support (e.g. Safari), might help narrow the issue down.

docs/get-started/README.md

@@ -1,9 +1,40 @@
 # Getting Started
 
-Welcome to luma.gl!
+To use luma.gl in an application, simply install it using `yarn`:
 
-This section has information about:
+```
+yarn add luma.gl
+```
+
+Note: While we'll use `yarn` for these instructions, as it's the tool we use for development, `npm` can be used as a drop-in substitute in most cases. A map of `npm` instructions to `yarn` is available [here](https://yarnpkg.com/lang/en/docs/migrating-from-npm/).
+
+## Using with Node.js
+
+luma.gl is built to run using [headless-gl](https://www.npmjs.com/package/gl) under Node.js, which can be extremely useful for unit testing. It is important to note that `headless-gl` only supports WebGL 1 and few extensions, so not all of luma.gl's features will be available.
+
+Use `yarn install gl` to install `headless-gl`. luma.gl will automatically use it when running under Node.js. You can then create a context using the `createGLContext` context function.
+
+```js
+import 'luma.gl';
+import {createGLContext, Model, ...} from '@luma.gl/core';
+const gl = createGLContext({width, height, ...});
+```
+
+## Interoperation with Other WebGL Applications
+
+luma.gl is build to interoperate cleanly with other WebGL applications using the same WebGL context. This is critical in geospatial applications, where `luma.gl` is often rendering over a base map drawn by another application.
+
+The key to luma.gl's interoperability is careful state management. luma.gl will track GL context changes and restore them after operations are complete.
+
+
+## Using luma.gl in Isorender Applications
+
+luma.gl is designed to support isorender application, i.e. the library can be loaded without problems under Node.js, as long as the application doesn't actually try to use WebGL (i.e. create WebGL contexts). However when luma.gl discovers that headless gl is not available it tries to give a helpful message explaining the situation. This can safely be ignored.
+
+Remember that you **can** actually create WebGL contexts under Node.js, as long as the headless `gl` is installed in your `node_modules` directory. More information on [using luma.gl with Node.js](/docs/get-started/using-with-node.md).
+
+
+## FAQ
+
+We occasionally mark github issues that contain answers to questions that pop up repeatedly with the [`FAQ` label](https://github.com/uber/luma.gl/issues?utf8=%E2%9C%93&q=label%3AFAQ+).
 
-* how to install luma.gl
-* how to run, copy, and modify the many luma.gl examples
-* How to use luma.gl with other frameworks in different environments.

docs/get-started/examples.md

@@ -1,60 +1,27 @@
 # Examples
 
-luma.gl contains a suite of examples that showcase various features of the framework. If you are curious to see what can be achieved by luma.gl, you are welcome to check out the live demos at [luma.gl's website](http://uber.github.io/luma.gl/#/examples/overview).
-
-If you'd like to poke around the example code and use the examples to learn how to develop using luma.gl, you can build and run the examples yourself using the instructions below.
-
+luma.gl's suite of examples are an excellent way to learn how to use the API. They're the same examples showcased on the [website](http://uber.github.io/luma.gl/#/examples/overview), but can be run and edited individually.
 
 ## Running Examples
 
-If you'd like to poke around the example code and use them to learn how to develop using luma.gl, you can build and run the examples yourself, following the instruction below:
-
 To run the examples, go to their directories, install and start, e.g:
 
 ```
 cd examples/core/instancing
-yarn         # or npm install
-yarn start   # or npm start
+yarn
+yarn start
 ```
 
-## Using the Latest Release Branch
-
-Note that luma.gl development happens on the `master` branch. While the goal is to always keep examples on `master` in working condition, they can temporarly be broken due to the core code being refactored for the next release. If you run into issues, or just want to be sure that you are running the latest stable version of the examples, just check out the latest release branch (e.g. `6.0-release`), and re-install and run the examples.
-
-To see available release branches:
-
-```
-git branch | grep -release
-```
-
-To check out a release branch:
-
-```
-git checkout 6.0-release
-```
-
-To go back to master:
-
-```
-git checkout master
-```
-
-
-## Copying Examples
-
-The examples are designed to be stand-alone so that they can be copied out of this repository, enabling you to use the examples as a basis for your own applications.
-
-Note: You can delete the last line in the webpack config file. That line handles the case of building the examples against the local luma.gl source (see "Development Mode" below), which is no longer applicable once the examples have been copied out of the repository.
+This will start a local development server and open the page in your browser. The example code will be in `app.js` in the example directly will automatically refresh the page.
 
+## Using the Latest Release Branch
 
-## Development Mode
+Note that luma.gl's `master` branch is its development branch and is often in flux. To ensure you're working with stable code, simply check out one of the release branches, e.g.
 
-Note that the `npm start` script in the example folders will use a published version of the luma.gl library (installed from npmjs.org) when bundling the code.
+`git checkout 7.0-release`
 
-To run the examples against the local luma.gl source code (useful for development and testing of luma.gl itself), use the `npm run start-local` command in the examples.
+To see all available release branches:
 
 ```
-cd examples/core/instancing
-yarn              # or npm install
-yarn start-local  # or npm run start-local
+git branch | grep -release
 ```