Merge pull request #148 from tangrams/readme

Readme

CONTRIBUTING.md

@@ -1,5 +1,18 @@
 # Contributing to Tangram
 
+## Quickstart
+
+To get Tangram up and running locally:
+
+1. Clone or download this repository:
+  	- clone in a terminal window with `git clone https://github.com/tangrams/tangram.git`
+  	- or download a zip directly: https://github.com/tangrams/tangram/archive/master.zip
+  	- or use [Bower](http://bower.io/): `bower install tangram`
+2. Start a webserver in the repository's directory:
+  	- in a terminal window, enter: `python -m SimpleHTTPServer 8000`
+  	- if that doesn't work, try: `python -m http.server`
+3. View the map at http://localhost:8000 (or whatever port you started the server on)
+
 ### Building
 
 If you'd like to contribute to the project or just make changes to the source code for fun, you'll need to install the development requirements and build the library:
@@ -37,4 +50,4 @@ We're using jshint to maintain code quality.
 
 ```shell
 make lint
-```
+```

README.md

@@ -9,14 +9,15 @@ Tangram is a JavaScript library for rendering 2D & 3D maps live in a web browser
 
 ## Quickstart
 
-1. Clone or download this repository:
-  	- clone in a terminal window with `git clone https://github.com/tangrams/tangram.git`
-  	- or download a zip directly: https://github.com/tangrams/tangram/archive/master.zip
-  	- or use [Bower](http://bower.io/): `bower install tangram`
-2. Start a webserver in the repository's directory:
-  	- in a terminal window, enter: `python -m SimpleHTTPServer 8000`
-  	- if that doesn't work, try: `python -m http.server`
-3. View the map at http://localhost:8000 (or whatever port you started the server on)
+Here's a [simple demo](https://tangrams.github.io/simple-demo/) ([repo here](https://github.com/tangrams/tangram-demo)) with a basic example of a Tangram map. The library includes a [Leaflet](http://leafletjs.com) plugin, `Tangram.LeafletLayer`, to provide basic web map pan/zoom functionality.
+
+Data sources, layers, and styling rules are written in a *scene file* ([here's an example](https://github.com/tangrams/simple-demo/blob/gh-pages/scene.yaml)). Armed with a scene file, you can create a Tangram scene and add it to a Leaflet like so:
+
+```
+var map = L.map('map');
+var layer = Tangram.leafletLayer({ scene: 'scene.yaml' });
+layer.addTo(map);
+```
 
 ## Demos
 
@@ -30,7 +31,6 @@ Tangram is a JavaScript library for rendering 2D & 3D maps live in a web browser
 
 [**Tangram-sandbox**](http://github.com/tangrams/tangram-sandbox) - More complex glsl shaders
 
-
 ## Vector Tiles
 
 Instead of loading traditional bitmap tiles, Tangram draws its own tiles from scratch, based on **vector tiles** that contain the source data.
@@ -39,11 +39,9 @@ Mapzen provides a free [vector tile service](http://mapzen.com/vector/) extracte
 
 Tangram currently supports GeoJSON/TopoJSON tiles as well as the [mapnik binary format](https://github.com/mapbox/vector-tile-spec), both of which can be generated by the [Mapzen vector tile service](http://mapzen.com/vector/). (Here's an [example GeoJSON tile](http://vector.mapzen.com/osm/all/14/4826/6161.json).)
 
-The library also includes a [Leaflet](http://leafletjs.com) plugin, `Tangram.LeafletLayer`, to provide basic web map pan/zoom functionality.
-
 ## Styling
 
-The scene file is where you specify data sources and layers, filter the data, and define and apply styles. (In our demos, this file is named scene.yaml.) The rules for doing these things are many and various, but the basics are pretty easy, and they are all meticulously documented in the Tangram Documentation https://github.com/tangrams/tangram/wiki.
+The *scene file* is where you specify data sources and layers, filter the data, and define and apply styles. (In our demos, this file is named scene.yaml.) The rules for doing these things are many and various, but the basics are pretty easy, and they are all meticulously documented in the Tangram Documentation https://github.com/tangrams/tangram/wiki.
 
 The scene file is written in YAML, which is a data-serialization format like JSON, but with less punctuation. Instead, data structures are specified with whitespace, like Python. One neat side benefit is that the format is super friendly to strings, which means you can write inline JavaScript and GLSL code straight into the scene file, without needing to wrap it in quotes or concatenate anything.