Update API key placeholders, broken links, style

docs/data-sources.md

@@ -2,7 +2,7 @@
 
 Mapzen Vector Tiles are powered by several major open data sets and we owe a tremendous debt of gratitude to the individuals and communities which produced them.
 
-**Attribution is required** for many of our data providers. See the [Attribution](attribution.md) document for more information.
+**Attribution is required** for many data providers. See the [Attribution](https://github.com/tilezen/vector-datasource/blob/master/docs/attribution.md) document for more information.
 
 ## What is sourced at what zooms?
 

docs/index.md

@@ -14,8 +14,7 @@ With vector tiles you have the power to customize the content and visual appeara
 
 To start integrating vector tiles to your app, you need a [developer API key](https://mapzen.com/documentation/overview/).
 
-* [API keys and rate limits](api-keys-and-rate-limits.md) - Don't abuse the shared service!
-* [Attribution requirements](attribution.md) - Terms of service for OpenStreetMap and other projects require attribution.
+* [Attribution requirements](https://github.com/tilezen/vector-datasource/blob/master/docs/attribution.md) - Terms of service for OpenStreetMap and other projects that require attribution.
 
 #### Requesting tiles
 
@@ -33,7 +32,7 @@ More information is available about how to [use the vector tile service](use-ser
 
 The Mapzen vector tile service provides [tiles in a variety of formats](use-service.md#formats), including [GeoJSON](http://geojson.org), [TopoJSON](https://github.com/mbostock/topojson/wiki), and the binary, protobuf-based [Mapbox Vector Tile (MVT) format](https://www.mapbox.com/vector-tiles/specification/).
 
-**We recommend** `TopoJSON` format for desktop web development, and `MVT` format for native mobile development. The Mapzen server gzips tiles automatically, so the TopoJSON file format is comparable in file size to MVT over the wire, and it's much friendlier to debug.
+**Mapzen recommends** `TopoJSON` format for desktop web development, and `MVT` format for native mobile development. The Mapzen server gzips tiles automatically, so the TopoJSON file format is comparable in file size to MVT over the wire, and it's much friendlier to debug.
 
 ##### Drawing a map
 

docs/layers.md

@@ -6,21 +6,21 @@ The [Mapzen vector tile service](https://mapzen.com/projects/vector-tiles) provi
 
 Data is organized into several thematic layers, each of which is named, for example; `buildings`, `pois`, and `water`. A selection of these layers are typically used for base map rendering, and are provided under the short-hand name `all`. Each layer includes a simplified view of OpenStreetMap data for easier consumption, with common tags often condensed into a single `kind` field as noted below.
 
-Need help displaying vector tiles in a map? We have several [examples](display-tiles.md) using Mapzen vector tiles to style in your favorite graphics library including Tangram, Mapbox GL, D3, and OpenLayers.
+Need help displaying vector tiles in a map? Here are several [examples](display-tiles.md) using Mapzen vector tiles to style in your favorite graphics library including Tangram, Mapbox GL, D3, and OpenLayers.
 
 ### Overview
 
 #### Data sources and attribution
 
-Mapzen primarily sources from OpenStreetMap, but includes a variety of other open data. For a full listing, view the [data sources](data-sources.md). Each source may require [attribution](attribution.md) in your project.
+Mapzen primarily sources from OpenStreetMap, but includes a variety of other open data. For a full listing, view the [data sources](data-sources.md). Each source may require [attribution](https://github.com/tilezen/vector-datasource/blob/master/docs/attribution.md) in your project.
 
 #### Feature names
 
 Most Mapzen vector tile features include a basic name property (`common`):
 
 * `name` - Generally the name the locals call the feature, in the local script.
 
-We support several additional name related properties (`optional`):
+It supports several additional name related properties (`optional`):
 
 * `alt_name`
 * `int_name`
@@ -36,13 +36,13 @@ We support several additional name related properties (`optional`):
 
 #### Name localization
 
-We include all language variants of the `name:*` values to enable full internationalization (when different than `name`).
+Mapzen includes all language variants of the `name:*` values to enable full internationalization (when different from `name`).
 
 Language variants are identified by an ISO 639-1 two-letter language code and optional country code, for example `en` for English and less commonly `en_GB` for British English. Mapzen [house styles](https://mapzen.com/products/maps/) designed in Tangram support displaying all language scripts.
 
 We additionally localize `alt_name:*` and `old_name:*` properties for features across all layers.
 
-For features in the `boundaries` layer, we support two additional variants `name:left` and `name:right` to support oriented labeling on the appropriate side of the boundary line (so the labeled polygon's text can appear inside that polygon consistently). _See planned bug fix [#1102](https://github.com/tilezen/vector-datasource/issues/1102)._
+For features in the `boundaries` layer, there are two additional variants `name:left` and `name:right` to support oriented labeling on the appropriate side of the boundary line (so the labeled polygon's text can appear inside that polygon consistently). _See planned bug fix [#1102](https://github.com/tilezen/vector-datasource/issues/1102)._
 
 **Localized name properties** (`common-optional`)**:**
 
@@ -56,7 +56,7 @@ For features in the `boundaries` layer, we support two additional variants `name
 
 Individual Mapzen vector tile layers can include mixed geometry types. This is common in the `landuse`, `water`, and `buildings` layers.
 
-A tile geometry can be one of 3 types:
+A tile geometry can be one of three types:
 
 * Point, MultiPoint
 * LineString, MultiLineString
@@ -94,15 +94,15 @@ Most Mapzen vector tile content is updated minutely from OpenStreetMap. Low and
 
 The current version of Mapzen vector tile "Tilezen" data model is **v1.2.0**.
 
-Our tiles are still in active development, but we promise to minimize backwards incompatable breaking changes. We list data model promises in the Tilezen [SEMANTIC VERSIONING](https://github.com/mapzen/vector-datasource/tree/master/SEMANTIC-VERSIONING.md) statement.
+Tiles are still in active development, but Mapzen promises to minimize backwards incompatible breaking changes. Data model promises are listed in the Tilezen [SEMANTIC VERSIONING](https://github.com/mapzen/vector-datasource/tree/master/SEMANTIC-VERSIONING.md) statement.
 
-If you're signed up for a [Mapzen API key](https://mapzen.com/developers) you should receive an email notifying you of upcoming changes before they are rolled out to production. We're also interested in your feedback at [email protected]!
+If you're signed up for a [Mapzen API key](https://mapzen.com/developers) you should receive an email notifying you of upcoming changes before they are rolled out to production. You can also send your feedback at [email protected]!
 
 Read the full details in the project [CHANGELOG](https://github.com/mapzen/vector-datasource/tree/v1.0.0/CHANGELOG.md).
 
 #### Feature ordering
 
-Ordering of features - which ones draw "on top of" other features - can be an important feature of display maps. To help out with this, we export a `sort_rank` property on some features which suggests in what order the features should appear. Lower numbers mean that features should appear "towards the back" and higher numbers mean "towards the front". These numbers are consistent across layers. The layers which include `sort_rank` on their features are: `boundaries`, `buildings`, `earth`, `landuse`, `roads`, `transit` and `water`.
+Ordering of features - which ones draw "on top of" other features - can be an important feature of display maps. To help out with this, there is a `sort_rank` property on some features which suggests in what order the features should appear. Lower numbers mean that features should appear "towards the back" and higher numbers mean "towards the front". These numbers are consistent across layers. The layers which include `sort_rank` on their features are: `boundaries`, `buildings`, `earth`, `landuse`, `roads`, `transit` and `water`.
 
 To facilitate **data visualization** overlays and underlays, the following client-side `order` ranges are suggested:
 

docs/use-service.md

@@ -9,33 +9,33 @@ To use Mapzen's hosted vector tile service in a project, [obtain an API key from
 Once you have your Mapzen API key you'll need include it with Vector Tile requests as a [URL query string](https://en.wikipedia.org/wiki/Query_string) like:
 
 ```
-?api_key=your_mapzen_api_key
+?api_key=your-mapzen-api-key
 ```
 
 # Use the Vector Tile service
 
 Request a single tile with this URL pattern to get started:
 
 ```
-https://tile.mapzen.com/mapzen/vector/v1/{layers}/{z}/{x}/{y}.{format}?api_key={your_mapzen_api_key}
+https://tile.mapzen.com/mapzen/vector/v1/{layers}/{z}/{x}/{y}.{format}?api_key=your-mapzen-api-key
 ```
 
 The [OpenStreetMap Wiki](http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) has more information on this url scheme.
 
 Here’s a sample tile in GeoJSON:
 
 ```
-https://tile.mapzen.com/mapzen/vector/v1/all/16/19293/24641.json?api_key=your_mapzen_api_key
+https://tile.mapzen.com/mapzen/vector/v1/all/16/19293/24641.json?api_key=your-mapzen-api-key
 ```
 
 ## Specify layers in the service
 
 Layers to return can specified as `all`, or as one or more layer names separated by commas. Using the `all` layer is more performant.
 
 
-`buildings`: https://tile.mapzen.com/mapzen/vector/v1/buildings/16/19293/24641.json?api_key=your_mapzen_api_key
+`buildings`: https://tile.mapzen.com/mapzen/vector/v1/buildings/16/19293/24641.json?api_key=your-mapzen-api-key
 
-`earth,landuse`: https://tile.mapzen.com/mapzen/vector/v1/earth,landuse/16/19293/24641.json?api_key=your_mapzen_api_key
+`earth,landuse`: https://tile.mapzen.com/mapzen/vector/v1/earth,landuse/16/19293/24641.json?api_key=your-mapzen-api-key
 
 ### Layers in the service's response