Merge pull request #709 from github/integrations-directory-docs-tweaks

kdaigle · kdaigle · commit ff546cc611b2 · 2015-10-09T11:42:07.000-04:00
Recommended edits for Integrations Directory docs
diff --git a/content/integrations-directory/getting-listed.md b/content/integrations-directory/getting-listed.md
@@ -7,7 +7,7 @@ title: Getting listed in the Integrations Directory | GitHub API
 * TOC
 {:toc}
 
-## Listing Requirements
+## Listing requirements
 
 ### Provide the right contacts
 
@@ -17,43 +17,43 @@ We want to be sure GitHub can contact your team, if needed. Specifically, we're
 * A security contact
 * An escalation contact
 
-All three are for GitHub-use only. If there's an urgent that needs your attention, we'll contact your escalation contact and expect a response within one business day. A delayed response from your escalation contact may result in temporary or permanent de-listing of your integration from the directory.
+All three are for GitHub-use only. If there's an urgent issue that needs your attention, we'll contact your escalation contact and expect a response within one business day. A delayed response from your escalation contact may result in temporary or permanent de-listing of your integration from the directory.
 
 ### Provide standard links
 
-We'd like to have a minimum set of links (in the Marketing Guidelines on the right) to include in every integration listing, so that our users have all the information they need. These are:
+We'd like to have a minimum set of links to include in every integration listing, so that our users have all the information they need. These are:
 
 - Documentation - Please provide a URL with more information on how to use your integration.
 - Terms of service - Please provide the Terms of Service URL for users using your integration.
 - Privacy Policy - If different than Terms of Service, please include the URL here.
 - Support - Please provide a URL or email address for users to contact you directly.
 - Status - You should provide us a URL that will be updated when your application is down or experiencing problems. This could be a status site, a blog, a Twitter account, or more. This URL should be publicly accessible.
-- Pricing - If you integration costs money or has differed priced tiers of service, please include this URL.
-- Installation - Provide the URL for direct installation for users. Note the oAuth requirement below.
+- Pricing - If your integration costs money or has differed priced tiers of service, please include this URL.
+- Installation - Provide the URL for direct installation for users. Note the OAuth requirement below.
 
 ### Provide updates to your listing
 
 We want GitHub users to have consistent messaging within the Integrations Directory and your
-marketing site. As your product changes, keep your Integration Directory listing up to date. We ask that you refresh the information at least once a year.
+marketing site. As your product changes, keep your Integration Directory listing up to date. We ask that you refresh the information at least once a year. Please send updates to [partnerships@github.com](mailto:partnerships@github.com).
 
 ### Provide categories for your listing
 
-Help GitHub users find your Integration Directory listing faster with the appropriate categories. Please send us your suggested categories for the listing (multiples are fine). We reserve the right to remove categories from a listing, but we won't add any categories without your approval. Currently, the following categories are available:
+Help GitHub users find your integration faster with the appropriate categories. Please send us your suggested categories for the listing. We reserve the right to remove categories from a listing, but we won't add any categories without your approval. Currently, the following categories are available:
 
 * Build
 * Collaborate
 * Deploy
 
-## Technical Requirements
+## Technical requirements
 
 ### Use TLS
 
 Anytime you display GitHub data in your integration, use TLS. If you also use [webhooks](https://developer.github.com/webhooks/) to receive updated data from GitHub, use SSL/TLS there too.
 
 ### Delete GitHub data once you lose access to the information
 
-Once you realize you've lost access to a user, organization, repository, and its related objects,
-please delete that information in your system within 60 days.
+Once you realize you've lost access to a user, organization, repository, or its related objects,
+delete that information in your system within 60 days.
 
 ## Choose your type of listing
 
@@ -82,5 +82,8 @@ account creation*.
 
 ## Send us your information
 
-In addition to this check, please follow the Marketing Guidelines on the right.  The best format for delivery is Markdown (.md) or plain text (.txt). Please attach images at the proper resolution, we aren't able to extract photos from PDFs or Word docs.
-Once you're ready just send the materials over emailto [partnerships@github.com](mailto:partnerships@github.com). Thanks! Looking forward to reviewing your listing!
+In addition to this checklist, please follow the [Marketing Guidelines](/integrations-directory/marketing-guidelines/) as well.  The best format for delivery is Markdown (.md) or plain text (.txt).
+
+Please attach images at the proper resolution. We aren't able to extract photos from PDFs or Word docs.
+
+Once you're ready, just send the materials over email to [partnerships@github.com](mailto:partnerships@github.com). Thanks! We're looking forward to reviewing your listing.
diff --git a/content/integrations-directory/index.md b/content/integrations-directory/index.md
@@ -5,6 +5,6 @@ layout: integrations-directory
 
 # Overview
 
-As one of our integrators, we're excited to tell the world about your GitHub integration at [https://github.com/integrations](https://github.com/integrations). To ensure the GitHub community has the best experience finding and using your integrations, we've outlined a short list of requirements to follow.
+As one of our integrators, we're excited to tell the world about your GitHub integration at [https://github.com/integrations](https://github.com/integrations). To ensure the GitHub community has the best experience finding and using your integrations, we've outlined a [short list of requirements](/integrations-directory/getting-listed/) to follow.
 
-We're happy to chat about these if you have any questions, feel free to reach out to [partnerships@github.com](mailto:partnerships@github.com) for additional detail.
+We're happy to chat about these if you have any questions. Feel free to reach out to [partnerships@github.com](mailto:partnerships@github.com) for additional detail.
diff --git a/content/integrations-directory/marketing-guidelines.md b/content/integrations-directory/marketing-guidelines.md
@@ -11,11 +11,11 @@ This document will help you write compelling and well-structured marketing mater
 
 ## One line blurb
 
-This is a short sentence (70 characters max), that'll show up right below your logo. It can be used for a tagline or quick summary of the integration itself.
+This is a short sentence (70 characters max), that'll show up right below your logo. It can be used for a tagline or quick summary of the integration.
 
-## Integration description
+## Description
 
-Write a single paragraph that describes your integration clearly and speaks directly to the audience (think “you” and “your” over “we” and “our”). Make sure to answer the following questions in your description:
+Write a single paragraph that describes your integration clearly and speaks directly to the audience (think “you” and “your” over “we” and “our”). Answer the following questions in your description:
 
 - What does it do?
 - How does it integrate with GitHub?
@@ -46,7 +46,7 @@ List some features to give people a better sense of what your integration offers
 - Does the feature have a name? What is it?
 - What does the feature do?
 - How does it help people build better software?
-- Does it interact with any external services? (i.e. can deploy to Heroku, Engine Yard Cloud, etc.)
+- Does it interact with any external services (e.g., can deploy to Heroku, Engine Yard Cloud, etc.)?
 - Does your feature require any setup?
 
 **Example**
@@ -65,11 +65,11 @@ List some features to give people a better sense of what your integration offers
 - Do not write in all caps to provide emphasis.
 - Write in [GitHub Flavored markdown](https://help.github.com/articles/github-flavored-markdown/).
 
-## Integration logo guidelines
+## Logo
 - Provide your integration logo as a 128x128 pixel PNG.
 - Negative space must be transparent.
 - Do not stretch or squish your logo to fill the space.
 - You'll need to attach this logo to your GitHub Application, before the listing is published.
 
 ## Samples
-Feel free to look at some of the listings on the current Directory listing, such as [Gitter](https://github.com/integrations/gitter) or [ZenHub](https://github.com/integrations/zenhub).
+Feel free to look at existing listings in the Integrations Directory, such as [Gitter](https://github.com/integrations/gitter) or [ZenHub](https://github.com/integrations/zenhub).
