WIP: new overview docs

Makefile

@@ -100,7 +100,7 @@ src-cartography:
 
 src-overview:
 	cp -r docs/overview src-overview
-
+	
 src-guides:
 	cp -r docs/guides src-guides
 

config/overview.yml

@@ -1,12 +1,20 @@
-site_name: Developer overview
+site_name: Get started
 docs_dir: src-overview
 site_dir: dist-overview
 
 pages:
-  - Overview: index.md
+  - 'Home': index.md
+  - 'Account settings': 'account-settings.md'
+  - 'Billing information': 'billing.md'
+  - 'API keys': 'api-keys.md'
+  - 'Rate limits': 'rate-limits.md'
+  - 'Support': 'support.md'
+
+# mz:redirects:
+#  'overview/#rate-limits': 'overview/rate-limits'
 
 extra:
-  site_subtitle: Get started developing with Mapzen's products
+  site_subtitle: Get started developing on the Mapzen platform by setting up your account, API keys, and billing information.
   project_repo_url: https://github.com/mapzen/mapzen-docs-generator
-  docs_base_url: https://github.com/mapzen/mapzen-docs-generator/tree/master/docs/overview
+  docs_base_url: https://github.com/mapzen/mapzen-docs-generator/tree/master/docs/overview/
   exclude_home_contents_in_toc: false

docs/overview/account-settings.md

@@ -0,0 +1,72 @@
+# Update your Mapzen account settings
+
+_Note: You may not see all billing and account settings options right now while your account is being upgraded. The rate limit and pricing information presented here will be fully effective for all accounts starting June 1, 2017._
+
+When you signed in on Mapzen’s website, you can view and modify your account settings. These include changing your email address and password, and updating your credit card and billing information.
+
+## Sign up for a Mapzen account
+
+1. Go to https://mapzen.com.
+2. Click `Sign Up`.
+3. Choose your authentication method. Create your account by entering your e-mail address and password, or if you have a [GitHub](https://github.com) account, you can use it for authentication. GitHub is a website that enables people to collaborate on a project.
+
+When you create an account, you need to agree to the Mapzen [Terms of Service](https://mapzen.com/terms/).
+
+In the future when you sign in, use either your email address and password or GitHub account, depending on how you registered originally. If you forgot your password, you can also attempt to reset it.
+
+To delete your account, you need to [contact Mapzen](mailto:[email protected]). If you are using GitHub, sign into your GitHub account and revoke [Mapzen Platform](https://help.github.com/articles/reviewing-your-authorized-applications-oauth/) as an authorized application.
+
+## Change your email address or password
+
+1. Sign in to your Mapzen account.
+2. In the top corner of the page, click `Account` and click `Settings`.
+3. If you are using an email address to sign in, you can update your email address and password.
+4. With GitHub authentication, you can change your email address where you receive communications from Mapzen. Note that this is the address that was part of your GitHub profile when you originally authenticated your Mapzen account.
+
+## Add your payment method
+
+To use any of Mapzen’s services above the free limits, you need to add a payment method to your account.
+
+If you do not have a valid credit card on file and you reach the free limits, your access to that Mapzen service will cease for the remainder of the month. You can continue to use other services up to their individual free limits.
+
+At the end of each month, Mapzen calculates your usage and bill, and your charges are paid automatically by the credit card on file.
+
+1. Sign in to your Mapzen account.
+2. In the top corner of the page, click `Account` and click `Settings`.
+3. In the `Billing` section, `Add Payment Method`.
+4. Enter your credit card information.
+
+If your account has any pending usage charges in a month, you can update it to a different credit card, but are unable to delete your credit card altogether until the balance has cleared.
+
+## Set monthly spending limits
+
+You can set limits on your spending each month. This gives you the comfort of knowing that your bill will not exceed the amount you specify. You will only be charged for what you use, which may be less than the limit you set for the month.
+
+To set a spending limit, you first need to add a payment method to your account. By default, there is no spending limit on your account, which means your usage (and potential bill) is unrestricted.
+
+Limits can be changed at any time, but cannot be set to an amount lower than the already accrued charges for that month. After you change your limit, the monthly spending limit stays the same month after month into the future. You will be notified by email as you approach your spending limit.
+
+The spending limit applies across all services. If you reach your spending limit by using only Mapzen Search, for example, you will not be able to use Mapzen Search or any other services beyond the free limits for the remainder of the month. Your account will not accumulate any charges for overages, but no results will be returned for your API requests. This means that your maps may no longer function.
+
+Rate limits are reset on the first day of every month at 00:00 UTC (Coordinated Universal Time).
+
+See https://mapzen.com/pricing for more information on current pricing and the limits available with the free plan.
+
+1. Sign in to your Mapzen account.
+2. In the top corner of the page, click `Account` and click `Settings`.
+3. Make sure you have a payment method on your account. You will not see additional billing information unless you have a credit card on file.
+4. In the `Billing` section, click `Update` under `Monthly spending limit`.
+5. Make sure your billing status is `Enabled`.
+6. Enter the maximum you want to spend across all Mapzen services.
+
+As you approach your spending limit, your choices are to increase your spending limits, adjust your usage, or accept that your access to higher rate limits will end.
+
+## Set your billing status
+
+When billing is enabled, you have access to Mapzen services at levels above the free limits and are agreeing to pay for your usage, up to your monthly spending limit, if one exists. By default, billing is enabled when you add a payment method to your account.
+
+To stop billing, set your billing status to disabled in the `Billing` section of your account settings. This has the effect of setting your monthly spending limit to $0 because you are only able to use Mapzen services up to the free limits of each product. If you exhaust the free limits, your maps may no longer function.
+
+Any charges that were pending before you disabled billing will still be charged to the credit card on file at the end of the current billing cycle. However, no further charges can accrue. The billing status remains as you set it until you change it in the future.
+
+Anytime you want to start billing again, set your billing status to `Enabled`.

docs/overview/api-keys.md

@@ -0,0 +1,56 @@
+# Create and manage your Mapzen API keys
+
+When signed in to your Mapzen account, you can access a dashboard that allows you to create, manage, and track the usage of your Mapzen API keys. An API key is a code that uniquely links API usage inside your application with your Mapzen account without needing a password.
+
+Mapzen's web services have various API endpoints that allow you to access web resources through a URL. You will need to include your API key in the URL you construct to send requests to Mapzen's services. For example, add an `api_key` URL parameter to any request, such as `?api_key=your-mapzen-api-key`. An API key works for any Mapzen service.
+
+You must include an API key when using Mapzen's services; requests sent without an API key return errors.
+
+## Create an API key
+
+1. Go to https://mapzen.com.
+2. In the top corner of the page, click `Account` and click `Dashboard`. This is where you can create, delete, and manage your API keys.
+3. Create a new key.
+4. Optionally, give the key a name so you can remember the purpose of the project.
+5. When you are ready to use it, copy the key and paste it into your code. In your query, the API key parameter should take the form of `api_key=your-mapzen-api-key`, substituting your actual API key for `your-mapzen-api-key` part of the example.
+
+_Note: The free rate limits are applied to your usage across your entire account. Creating multiple keys does not increase these limits._
+
+## Choose an API key strategy for your app
+
+The simplest workflow is for your app to employ a centralized API key for all users. This could mean that you deploy your app with a single key with enough capacity to cover all of your users’ usage. A valid variation is to create and deploy multiple keys if you want to monitor usage and billing for a particular client or function within your app.
+
+In this model, the API keys in your app are linked to your Mapzen account. This makes you responsible for the costs associated with all of the usage for the keys that are deployed in your app. You can set a spending limit on your account to avoid unexpected charges, although be aware that the app may not function after the spending limit is reached.
+
+The alternative and more complex API key workflow is for your app to provide an option for users to enter an API key from their own Mapzen accounts. Doing this allows your users to have their own free rate limits, and makes them individually liable for their usage costs. If you implement this method, your app should clearly indicate that a valid Mapzen API key is required. Otherwise, your users will see errors if they fail to include an API key when using Mapzen's services.
+
+## Protect your API keys
+
+If you want to keep your API key private, you can consider using a proxy system to hide the key from your users.
+
+Here is an example of how to do this with [mapzen.js](https://mapzen.com/documentation/mapzen-js/). In your YAML scene file that defines the Tangram map, add a `sources` parameter for the API key.
+
+```
+sources:
+    mapzen:
+      [...]
+      url_params:
+          api_key: global.sdk_mapzen_api_key
+```
+
+Then, in the JavaScript, use your actual key in place of `your-mapzen-api-key` in this code.
+
+```
+var map = L.Mapzen.map('map', {
+  tangramOptions: {
+    scene: {
+      [...]
+      global: {
+        sdk_mapzen_api_key: 'your-mapzen-api-key'
+      }
+    }
+  }
+}
+```
+
+If you believe your API key has been compromised or used without your knowledge, contact [Mapzen](mailto:[email protected]). You can also delete API keys or rotate them periodically in your app. There is not currently a default way to limit an API key for usage only on a particular web domain.

docs/overview/billing.md

@@ -0,0 +1,32 @@
+# View your current usage and bill
+
+_Note: You may not see all billing and account settings options right now while your account is being upgraded. The rate limit and pricing information presented here will be fully effective for all accounts starting June 1, 2017._
+
+When you are signed in with your Mapzen account, you can view your current usage and charges due.
+
+You can think of your Mapzen bill as similar to a home utility bill, where your charges are dependent on how much water or electricity, for example, you consumed in a month.
+
+Because there are no paid tiers, you pay for each individual API request you make above the free rate limits. Although you may see pricing listed in units of 1,000, requests are not purchased in bundles. For example, $0.05 per 1,000 is intended to be a simpler way of representing that each request is $0.00005.
+
+Billing is post-paid after the month ends, and there are no prepayment discounts available. There are no minimum fees for maintaining a Mapzen account, even if you have no usage for a while.
+
+The billing currency is the United States Dollar (USD). Mapzen handles the payment of sales or usage tax that may be required in your area.
+
+If you need to update your credit card information, you can do that from your [Mapzen account settings](account-settings.md#add-your-payment-method). If you have questions about your bill or are having problems paying it, please contact Mapzen at [email protected].
+
+## View your usage
+
+To check your usage, sign in to your developer account and review your dashboard.
+
+1. Sign in to your Mapzen account.
+2. In the top corner of the page, click `Account` and click `Dashboard`. This page shows your current Mapzen API keys.
+3. Click one of your API keys in the list and click `Usage`. The graphs show the number of requests on this key for each product.
+
+## Request a bill credit for service issues
+
+_Note: This is only available to users who subscribe to premium support, which includes a service-level agreement._
+
+While Mapzen hopes you never experience an outage or downtime in services, you can request a credit in the event that issues occur. See the Mapzen [Terms of Service](https://mapzen.com/terms/) for more information about your rights and requirements, and keep in mind that those terms supersede any documentation content here.
+
+1. If you are a premium support subscriber and believe that Mapzen has not met the uptime percentage in the developer agreement, record any information about the downtime you can, such as the service name and API, date and time, and estimated outage amount.
+2. Within 15 days, send this to [Mapzen support](mailto:[email protected]) for review.