First pass at updating docs for Collections

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,10 +1,10 @@
 - [ ] I followed the contributing guidelines: https://github.com/github/explore/blob/master/CONTRIBUTING.md
 
 I am:
-  - [ ] Suggesting edits to an existing Topic page
-  - [ ] Curating a new Topic page
+  - [ ] Suggesting edits to an existing topic or collection
+  - [ ] Curating a new topic or collection
 
-***********EDITING AN EXISTING TOPIC PAGE************
+***********EDITING AN EXISTING TOPIC OR COLLECTION************
 
 I'm suggesting these edits to an existing topic:
 - [ ] Image (and my file is `*.png`, square, dimensions 288x288)
@@ -13,12 +13,12 @@ I'm suggesting these edits to an existing topic:
 Please explain why these changes are necessary:
 
 
-************CURATING A NEW TOPIC PAGE************
+************CURATING A NEW TOPIC OR COLLECTION************
 
 - [ ] I've formatted my changes as a new folder directory, named for the topic as it appears in the URL on GitHub (e.g. `https://github.com/topics/[NAME]`)
 - [ ] My folder contains a `*.png` image (if applicable) and `index.md`
 - [ ] All required fields in my `index.md` conform to the Style Guide and API docs: https://github.com/github/explore/tree/master/docs
 
-Please explain why you think this Topic page should be curated:
+Please explain why you think this topic or collection should be curated:
 
 **Please note: we will close your PR without comment if you do not check the boxes above and provide ALL requested information.**

CONTRIBUTING.md

@@ -1,39 +1,87 @@
 # Contributing
 
-Hi there! We're excited you've got ideas for an existing or new topic page. Your help makes Explore valuable to others in your community.
+Hi there! We're excited you've got ideas to improve topics and collections. Your helping the community discover valuable information.
 
 This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
 
-There are a few ways you can contribute: improving an existing topic page, or curating a new topic page.
+There are a few ways you can contribute:
+
+- Improving an existing topic or collection
+- Curating a new topic topic or collection
 
 As you write content, check out the [Style Guide](./docs/styleguide.md) to learn what each field means, and how they should be formatted. Following the style guide will improve the chances of your contribution being accepted.
 
-Note: updates won't immediately appear once we've merged your PR. We pull in these changes regularly to GitHub.
+Note: Updates won't immediately appear once we've merged your PR. We pull in these changes regularly to GitHub.
 
-## Improving an existing topic page
+## Improving an existing topic or collection
 
-If a topic page already exists, it will be listed in the [topics directory](https://github.com/github/explore/tree/master/topics). The topic name should match its URL, e.g. `https://github.com/topics/rails` corresponds to the [`rails` folder](https://github.com/github/explore/tree/master/topics/rails).
+If a topic or collection already exists, it will be listed in its respective directory:
 
-To improve an existing topic page, please **open a pull request** with your proposed changes:
+- [Topics](https://github.com/github/explore/tree/master/topics)
+- [Collections](https://github.com/github/explore/tree/master/collections)
 
-* To update the image, replace the image inside the topic's folder
-* To update the content, edit the `index.md` inside the topic's folder
+The topic or collection name should match its URL, e.g. `https://github.com/topics/rails` corresponds to the [`topics/rails` directory](https://github.com/github/explore/tree/master/topics/rails).
 
-The [pull request template](./.github/PULL_REQUEST_TEMPLATE.md) provides guidance on the information you need to include.
+To make an improvement, please **open a pull request** with your proposed changes:
+
+### Update the image
+
+To update the image, simply replace the image inside the topic or collection's directory
+
+### Update text & links
+
+To update text and links, edit the `index.md` inside the topic or collection's directory. These files are formatted using a combination of [front matter](https://jekyllrb.com/docs/frontmatter/) and simple body content.
+
+For **topics**, you'll notice that, in examples like "[algolia](https://raw.githubusercontent.com/github/explore/master/topics/algolia/index.md)," data like the topic's canonical URL, Wikipedia URL, or display name are called out in key-value pairs; while its detailed description is accounted for in the body of the document.
+
+_/topics/algolia/index.md_:
+```
+---
+aliases: algoliasearch, algolia-search
+related: instantsearch, instant-search
+created_by: Nicolas Dessaigne, Julien Lemoine
+display_name: Algolia
+github_url: https://github.com/algolia/
+logo: algolia.png
+released: October 23, 2012
+short_description: Algolia is a hosted search API for web and mobile applications.
+topic: algolia
+url: https://www.algolia.com/
+wikipedia_url: https://en.wikipedia.org/wiki/Algolia
+---
+Algolia is a hosted API for building search into web and mobile applications, with typo-tolerance, fully configurable relevance, and other tools for making great search experiences.
+```
+
+---
+
+Similarly, **collections** like "[music](https://raw.githubusercontent.com/github/explore/master/collections/music/index.md)" call out things like their author and display name in key-value pairs -- with a detailed description in the body of the document. Most importantly, though, collections identify their individual collection items in a comma-separated string value for the key "items."
+
+_/collections/music/index.md_:
+
+```
+---
+items: beetbox/beets, scottschiller/SoundManager2, CreateJS/SoundJS, musescore/MuseScore, tomahawk-player/tomahawk, cashmusic/platform, mopidy/mopidy, AudioKit/AudioKit, Soundnode/soundnode-app, gillesdemey/Cumulus, metabrainz/picard, overtone/overtone, samaaron/sonic-pi
+display_name: Music
+created_by: jonrohan
+---
+Drop the code bass with these musically themed repositories.
+```
+
+---
+
+The [pull request template](./.github/PULL_REQUEST_TEMPLATE.md) also provides guidance on the information you need to include.
 
 **Please fill out the pull request template completely.** If you do not fill out the template, your PR will be closed.
 
-## Curating a new topic page
+## Curating a new topic or collection
 
-If a topic page is not yet curated, it will NOT be listed in the [topics directory](https://github.com/github/explore/tree/master/topics). The default layout on `https://github.com/topics/foo` looks like this:
+If a topic or collection is not yet curated, it will NOT be listed in its respective directory.
 
-![topic page](https://user-images.githubusercontent.com/1840802/30932236-c9c397d2-a37b-11e7-94be-5c9847ea2d71.png)
-
-We are likely to consider suggestions to curate a topic page that is valuable to GitHub's community. Valuable topics include those that are already [widely used by repositories](https://help.github.com/articles/classifying-your-repository-with-topics/), or a topic that currently lacks important information. When suggesting content for a topic page, please consider how to make your contribution broadly useful and relevant to others, rather than serving a specific use case.
+We are likely to consider suggestions to curate a topic or collection that is valuable to GitHub's community. Valuable topics, for example, include those that are already [widely used by repositories](https://help.github.com/articles/classifying-your-repository-with-topics/), or a topic that currently lacks important information. When suggesting content, please consider how to make your contribution broadly useful and relevant to others, rather than serving a specific use case.
 
 Please note that all suggestions must adhere to GitHub's [Community Guidelines](https://help.github.com/articles/github-community-guidelines/) and [Terms of Service](https://help.github.com/articles/github-terms-of-service/). Per our Terms of Service, [you are responsible](https://help.github.com/articles/github-terms-of-service/#d-user-generated-content) for the content you contribute, and you must have the rights to use it.
 
-To propose a new topic page, please **open an pull request** with your proposed changes. The [API docs](./docs/API.md) and [style guide](./docs/styleguide.md) provide guidance on the information you need to include and how it should be formatted.
+To propose a new topic or collection, please **open an pull request** with your proposed additions. The [API docs](./docs/API.md) and [style guide](./docs/styleguide.md) provide guidance on the information you need to include and how it should be formatted.
 
 This repository includes [a list of the most-used GitHub topics that don't yet have extra context](topics-todo.md). If your pull request adds one of these topics, please update topics-todo.md so that the topic is checked (marked complete).
 

README.md

@@ -2,19 +2,17 @@
 
 [![Build Status](https://travis-ci.org/github/explore.svg?branch=master)](https://travis-ci.org/github/explore)
 
-<img src="https://user-images.githubusercontent.com/1840802/31236555-436777c4-a9a9-11e7-8377-c5c4c4c7722e.png" width="650" />
+This repository houses all of the community-curated content for GitHub Topics and Collections.
 
-Topic pages, curated by the community.
+[Topics](https://help.github.com/articles/about-topics/) help you explore repositories in a particular subject area, learn more about that subject, and find projects to contribute to.
 
-[Topics](https://help.github.com/articles/about-topics/) help you explore repositories in a particular subject area, learn more about a subject area, and find projects to contribute to.
+[Collections](http://github.com/collections) help you discover hand-picked repositories, developers, organizations, videos, and articles that share a common theme.
 
-If you want to suggest edits to an existing topic page, or curate a new topic page, read our [contributing guide](CONTRIBUTING.md) to get started. You can [review a list of popular topics that need more context](topics-todo.md) to get an idea of where to start.
+If you want to suggest edits to an existing topic page or collection, or curate a new one, read our [contributing guide](CONTRIBUTING.md) to get started. You can also [review a list of popular topics that need more context](topics-todo.md) to get an idea of where to start.
 
 ## Running tests
 
-There are some lint tests in place to ensure each topic is formatted in the way we expect. Travis
-CI will run the tests automatically. If you want to run the tests yourself locally, you will need
-Ruby and Bundler installed.
+There are some lint tests in place to ensure each topic is formatted in the way we expect. Travis CI will run the tests automatically. If you want to run the tests yourself locally, you will need Ruby and Bundler installed.
 
 You can run the tests using:
 

docs/API.md

@@ -1,4 +1,4 @@
-##  Making edits to a topic page
+##  Making edits to a topic
 
 If you're making edits to a topic page, the following fields are available for use. Not all fields are required.
 
@@ -64,3 +64,29 @@ Acceptable formatting:
 
 ### The body of your document
 (required) A longer description of the topic, which will appear on its topic page. Must be 1,000 characters or less. Should not be the same as `short_description`. Some Markdown is allowed, such as links. Emoji are allowed.
+
+##  Making edits to a collection
+
+If you're making edits to a collection, the following fields are available for use. Not all fields are required.
+
+### items
+A comma-separated string containing any of the following values:
+
+- GitHub repository path (e.g. `defunkt/dotjs`)
+- GitHub username (e.g. `defunkt`)
+- GitHub organization (e.g. `github`)
+- Any web URL (e.g. `https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners`)
+- Any YouTube video URL (e.g. `https://www.youtube.com/watch?v=0fKg7e37bQE`)
+
+A complete `items` key-value pair might look like:
+
+`items: pybee/batavia, Homebrew/brew, https://www.youtube.com/watch?v=dSl_qnWO104`
+
+### created_by
+(if applicable) GitHub username of the person and/or organization that authored the collection.
+
+### display_name
+(required) The collection name that will be displayed on its page (ex. `How to choose (and contribute to) your first open source project`). Should use proper noun capitalization. Emoji are not allowed.
+
+### The body of your document
+(required) A longer description of the collection, which will appear on its page. Must be 1,000 characters or less. Some Markdown is allowed, such as links. Emoji are allowed.

docs/styleguide.md

@@ -24,7 +24,7 @@ Always use the [Oxford comma](https://en.wikipedia.org/wiki/Serial_comma).
 Include and spell out the month. Include the day number without the "th" or "nd" at the end, for example: October 12.
 
 ### Exclamation points
-Avoid exclamation points in topic pages.
+Avoid exclamation points in topic pages and collections.
 
 ### GitHub
 Always use correct capitalization when referring to “GitHub” or “Git”. Never use “GitHub” or “Git” as a verb.