explore Documentation

1. Project Overview & Quickstart (github/explore) Copy Chapter

File: README.md Copy Chapter

GitHub Explore

This repository houses all of the community-curated content for GitHub Topics and Collections.

Topics help you explore repositories in a particular subject area, learn more about that subject, and find projects to contribute to.

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 Collection, or curate a new one, read our contributing guide to get started.

Running tests Copy Chapter

There are some lint tests in place to ensure each Topic is formatted in the way we expect. GitHub
Actions 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:

bundle install
bundle exec rubocop

Licenses Copy Chapter

Content is released under CC-BY-4.0 which gives you permission to use content for almost any purpose (but does not grant you any trademark permissions). See notices for complete details, including attribution guidelines, contribution terms, and software and third-party licenses and permissions.

File: docs/API.md Copy Chapter

Making edits to a topic Copy Chapter

If you're making edits to a topic page, the following fields are available for use. Not all fields are required.

aliases Copy Section

(if applicable) Synonyms for the topic name. For example, react and reactjs are aliases. You
should only list an alias for your topic if the majority of repositories using that alias are
referring to the same subject matter as the topic. You should not list another topic as an alias
if the alias is a superset of your topic.

For example, api makes sense in the related field for the graphql topic, but because many
repositories tagged with api are not to be associated with graphql, api does not make sense
in the aliases field for graphql.

Each alias must be formatted like that topic's topic field (same as the URL slug). Acceptable formatting:

• Starts with a letter or number
• Contains only letters, numbers, and hyphens
• At most 35 characters long

created_by Copy Section

(if applicable) Names of the people and/or organizations who authored the topic (NOT your name). For example, Jordan Walke is the author of react.

display_name Copy Section

(required) The topic name that will be displayed on the topic page (ex. React). Should use proper noun capitalization. Emoji are not allowed.

github_url Copy Section

(if applicable) URL of the topic's official GitHub organization or repository. Must start with https://github.com/.

logo Copy Section

(if applicable) The official logo associated with that topic. You must have permission to use this logo. If no official logo exists, do not include an image.

If you're submitting content for a topic page, upload the image to the topic's folder and put its name (ex. logo.png) here. The image must be square, *.png format, dimensions 288x288 and no larger than 75 kB. The file name must be the same as the topic with an image extension.

related Copy Section

(if applicable) Any related topics you can think of. Related topic suggestions are automatically generated by GitHub, but you have the option to call out any specific topics here.

Each related topic must be formatted like that topic's topic field (same as the URL slug). Acceptable formatting:

• Starts with a letter or number
• Contains only letters, numbers, and hyphens
• At most 35 characters long

Formatted as topic1, topic2, topic3.

released Copy Section

(if applicable) Date of first release. Formatted as MONTH DD, YYYY, MONTH YYYY, or just YYYY.

short_description Copy Section

(required) A short description of the topic, which will be used on the Explore homepage, Topics subpage, and other preview areas. Must be 130 characters or less. Emoji are not allowed.

topic Copy Section

(required) Name of the topic, which will be used in the URL, e.g. https://github.com/topics/[URL]. Formatted as lowercase.

Acceptable formatting:

• Starts with a letter or number
• Contains only letters, numbers, and hyphens
• At most 35 characters long

url Copy Section

(if applicable) URL to the topic's official website

wikipedia_url Copy Section

(if applicable) URL to a Wikipedia article about the topic

The body of your document Copy Section

(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 Copy Chapter

If you're making edits to a collection, the following fields are available for use. Not all fields are required.

items Copy Section

A YAML list 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 list might look like:

items:
 - pybee/batavia
 - Homebrew/brew
 - https://www.youtube.com/watch?v=dSl_qnWO104

created_by Copy Section

(if applicable) GitHub username of the person and/or organization that authored the collection.

display_name Copy Section

(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 Copy Section

(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.

File: docs/styleguide.md Copy Chapter

Topic Page Style Guide

From the GitHub Style Guide:

Words are an important part of how software works. Just as we have a style guide for our code, we have a style guide for our tone and our voice. Even though there may be dozens of people creating a product, it should still sound like we speak in one consistent voice.

The way we write is just as important as the way we build. Consider these things when writing copy.

Principles Copy Chapter

• Make it approachable. Use familiar language and don't assume the reader has prior topic knowledge.
• Keep it concise. Use the simplest possible language and link to outside content for deeper dives.
• Think about the community. Add content that will benefit many vs. an individual.

Grammar and usage Copy Chapter

Ampersands Copy Section

Use "and" rather than an ampersand unless you’re referencing a brand name, for example: Procter & Gamble.

Commas Copy Section

Always use the Oxford comma. 

Dates Copy Section

Include and spell out the month. Include the day number without the "th" or "nd" at the end, for example: October 12.

Exclamation points Copy Section

Avoid exclamation points in topic pages and collections.

GitHub Copy Section

Always use correct capitalization when referring to “GitHub” or “Git.” Never use “GitHub” or “Git” as a verb.

Numbers Copy Section

Write out “one” and every number less than 10.

Users Copy Section

Avoid using "users" in favor of developers, people, or a more specific description of the group of people.

Words that can be tricky Copy Section

• Agile (e.g. agile development): Don’t capitalize “agile” unless it’s starting a sentence.
• Email: Use “email”, not "e-mail."
• Internet: Don’t capitalize “internet” unless it’s starting a sentence.
• Open source:
  • Adjective: “Open source” is always lowercase, except when at the start of the sentence. You can use it as an adjective without a hyphen, as in “open source project” or “open source software.”
  • Noun: You can also use the term on its own to refer to open source in general, as in “give back to open source."
  • Verb: It’s acceptable to use open source as a verb when referring to a project that has been “open sourced” or that you intend to “open source.”
• Pull request: Never abbreviate "pull request." "Pull request" is always lowercase unless it's starting a sentence.
• Repository: Never abbreviate "repository." "Repository" is always lowercase unless it's starting a sentence.

File: topics/wiki/index.md Copy Chapter

aliases: wikis display_name: Wiki related: mediawiki, wikipedia short_description: Wikis are public, online repositories of information; created and often edited by many writers. topic: wiki wikipedia_url: https://en.wikipedia.org/wiki/Wiki Copy Chapter

Popularized by Wikipedia, wikis aim to be a comprehensive reference material to either specific or general subjects. Wikis typically consist of lots of individual articles, updated by a team of volunteer writers.

Wikis are frequently hosted using open source software due to the open source nature of HTML; a popular example amongst these projects is MediaWiki, being repsonsible for Wikipedia's backend.

GitHub allows for each repository to host a wiki of their own, allowing for detailed documentation of any repository's function. GitHub wikis may be relevant to continued development, relevant to those utilizing a repository's application, or a repository's entire purpose.

File: topics/documentation/index.md Copy Chapter

aliases: docs, documentations, documentation-generator display_name: Documentation short_description: Documentation is a set of information that describes a product to its users. topic: documentation wikipedia_url: https://en.wikipedia.org/wiki/Software_documentation related: tutorial, man-page, documentation-as-code, docblock, doc-gen, api-documentation, knowledge-base, design-document Copy Chapter

Documentation is a set of information that describes a product to its users, including what it is, how it operates, and how to use it.

2. Official Technical Reference & Guides (github/docs) Copy Chapter

GitHub Docs

Welcome to GitHub Docs! GitHub’s documentation is open source, meaning anyone from inside or outside the company can contribute. For full contributing guidelines, visit our contributing guide.

Quick links by contributor type Copy Chapter

• Hubbers (GitHub employees): See CONTRIBUTING.md in the docs-content repository for GitHub-specific processes.

• Open source contributors: See CONTRIBUTING.md in the docs repository for a quick-start summary.

How we sync changes across Docs repositories Copy Chapter

There are two GitHub Docs repositories:

• github/docs (public): Open to external contributions

• github/docs-internal (private): For GitHub employee contributions.

The two repositories sync frequently. Content changes in one are reflected in the other. Hubbers might prefer to post in docs when working with a customer, but docs has limitations on the types of contributions it accepts to safeguard the site and our workflows. Internal contributions should usually go to docs-internal.

Important: The docs repository accepts contributions to content files (.md files in /content and select /data sections like reusables only). Infrastructure files, workflows, and site-building code are not open for external modification.

New to contributing Copy Chapter

Here are some resources to help you get started with open source contributions:

• Finding ways to contribute to open source on GitHub
• Set up Git
• GitHub flow
• Collaborating with pull requests

License Copy Chapter

This project is dual-licensed under:

• Creative Commons Attribution 4.0 - for documentation and content in the assets, content, and data folders (see LICENSE)
• MIT License - for code (see LICENSE-CODE)