Merge pull request github#111 from github/onboarding

Improving the onboarding experience for Docs Open source

CONTRIBUTING.md

@@ -1,5 +1,58 @@
 # Contributing to this repository <!-- omit in toc -->
-We welcome contributions from the community. Read on to learn about the ways you can contribute to GitHub Docs.
+
+## Getting started <!-- omit in toc -->
+
+Before you begin:
+- This site is powered by Node.js. Check to see if you're on the [version of node we support](contributing/development.md).
+- Have you read the [code of conduct](CODE_OF_CONDUCT.md)?
+- Check out the [existing issues](https://github.com/github/docs/issues) & see if we [accept contributions](#types-of-contributions-memo) for your type of issue.
+
+### Use the 'make a contribution' button
+
+![](./assets/images/make-contribution.gif)
+
+Navigating a new codebase can be challenging, so we're making that a little easier. As you're using docs.github.com, you may come across an article that you want to make an update to. You can click on the **make a contribution** button right on that article, which will take you to the file in this repo where you'll make your changes.
+
+Before you make your changes, check to see if an [issue exists](https://github.com/github/docs/issues/) already for the change you want to make.
+
+### Don't see your issue? Open one
+
+If you spot something new, open an issue using a [template](https://github.com/github/docs/issues/new/choose). We'll use the issue to have a conversation about the problem you want to fix.
+
+### Ready to make a change? Fork the repo
+
+Fork using GitHub Desktop:
+
+- [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop.
+- Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
+
+Fork using the command line:
+- [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them.
+
+### Make your update:
+Make your changes to the file(s) you'd like to update. Here are some tips and tricks for [using the docs codebase](#working-in-the-githubdocs-repository).
+  - Are you making changes to the application code? You'll need **Node.js v14** to run the site locally. See [contributing/development.md](contributing/development.md).
+  - Are you contributing to markdown? We use [GitHub Markdown](contributing/content-markup-reference).
+
+### Open a pull request
+When you're done making changes and you'd like to propose them for review, use the [pull request template](#pull-request-template) to open your PR (pull request).
+
+### Submit your PR & get it reviewed
+- Once you submit your PR, others from the Docs community will review it with you. The first thing you're going to want to do is a [self review](#self-review).
+- After that, we may have questions, check back on your PR to keep up with the conversation.
+- Did you have an issue, like a merge conflict? Check out our [git tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) on how to resolve merge conflicts and other issues.
+
+### Your PR is merged!
+Congratulations! The whole GitHub community thanks you. :sparkles:
+
+Once your PR is merged, you can be added as a contributor in the [readme](README.md#contributors-).
+
+### Keep contributing as you use GitHub Docs
+
+Now that you're a part of the GitHub Docs community, you can keep participating in many ways.
+
+**Learn more about contributing:**
+
 - [Types of contributions :memo:](#types-of-contributions-memo)
   - [:mega: Discussions](#mega-discussions)
   - [:beetle: Issues](#beetle-issues)
@@ -26,10 +79,10 @@ We welcome contributions from the community. Read on to learn about the ways you
 - [Windows](#windows)
 
 ## Types of contributions :memo:
-You can contribute to the GitHub Docs content and site in several ways.
+You can contribute to the GitHub Docs content and site in several ways. This repo is a place to discuss and collaborate on docs.github.com! Our small, but mighty :muscle: docs team is maintaining this repo, to preserve our bandwidth, off topic conversations will be closed.
 
 ### :mega: Discussions
-Discussions are where we have conversations. 
+Discussions are where we have conversations.
 
 If you'd like help troubleshooting a docs PR you're working on, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
 
@@ -39,7 +92,7 @@ If you'd like help troubleshooting a docs PR you're working on, have a great new
 If you've found something in the content or the website that should be updated, search open issues to see if someone else has reported the same thing. If it's something new, open an issue using a [template](https://github.com/github/docs/issues/new/choose). We'll use the issue to have a conversation about the problem you want to fix.
 
 ### :hammer_and_wrench: Pull requests
-A [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository. 
+A [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository.
 
 When we merge those changes, they should be deployed to the live site within 24 hours. :earth_africa: To learn more about opening a pull request in this repo, see [Opening a pull request](#opening-a-pull-request) below.
 
@@ -66,22 +119,11 @@ You can browse existing issues to find something that needs help!
 Labels can help you find an issue you'd like to help with.
 - The [`good-first-issue` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue) is for problems or updates we think are ideal for beginners.
 - The [`content` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) is for problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown.
-- The [`engineering` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) is for problems or updates in the docs.github.com website. These will usually require some knowledge of JavaScript/Node.js or YAML to fix. 
+- The [`engineering` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) is for problems or updates in the docs.github.com website. These will usually require some knowledge of JavaScript/Node.js or YAML to fix.
 
 ## Opening a pull request
 You can use the GitHub user interface :pencil2: for some small changes, like fixing a typo or updating a readme. You can also fork the repo and then clone it locally, to view changes and run your tests on your machine.
 
-### Fork using GitHub Desktop
-[Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop. Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
-
-### Fork using the command line
-1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) the repo.
-2. Open the terminal.
-3. Enter the following command. Use your GitHub username instead of `YOUR-USERNAME`.
-   ```
-   git clone [email protected]:YOUR-USERNAME/docs
-   ```
-
 ## Working in the github/docs repository
 Here's some information that might be helpful while working on a Docs PR:
 
@@ -97,69 +139,10 @@ Here's some information that might be helpful while working on a Docs PR:
 
 - [Liquid](/contribution/liquid-helpers.md) - We use liquid helpers to create different versions of our content.
 
-- [Scripts](/script/README.md) - The scripts directory is the home for all of the scripts you can run locally. 
+- [Scripts](/script/README.md) - The scripts directory is the home for all of the scripts you can run locally.
 
 - [Tests](/tests/README.md) - We use tests to ensure content will render correctly on the site. Tests run automatically in your PR, and sometimes it's also helpful to run them locally.
 
-## Resolving merge conflicts
-When you try to merge two branches that change the same part of the same file, you will get a merge conflict.
-
-### In the GitHub user interface
-You can resolve the merge conflicts in the [GitHub UI](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github). This is useful for small conflicts, but if the conflict is more involved, you'll want to use your editor.
-
-#### Editing the file and committing the changes
-
-1. On the command line or GitHub Desktop, note the file that contains merge conflicts.
-2. Open the file in your editor.
-3. In the file, look for the merge conflict markers. (this is what it looks like in Atom)
-
- ```command-line
-  <<<<<<< HEAD
-
-  Here are your changes.
-  =====================
-  Here are the changes you are pulling in.
-  >>>>>>> main
-```
-4. Decide which changes to keep and delete the unwanted changes and the merge conflict markers. If there are multiple files with merge conflicts, repeat this step until you resolve all conflicts.
-
- ```command-line
-  Here are your changes.
-```
-
-**Note**: Resolving merge conflicts requires thought; it isn't purely mechanical and rote. Sometimes you outright accept your own changes, sometimes you take the upstream changes, and sometimes you combine the two to make a glorious hybrid update.
-
-5. To commit your new changes:
-- Using Desktop:
-  - Check out this [GitHub Desktop](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/committing-and-reviewing-changes-to-your-project) article.
-
-- Using the terminal: 
-  - Stage the file (or files) you just modified for commit.
-
- ```command-line
-  $ git add <EXAMPLE-CHANGED-FILE.md>
-```
-  - Commit the file to your local branch.
-
- ```command-line
-  $ git commit -m "resolves merge conflicts"
-```
-  - Push the committed changes to the remote branch of the repository on GitHub.
- ```command-line
-  $ git push origin
-```
-
-## Troubleshooting
-If you get stuck while you're trying to contribute, see if someone else has had a similar problem in [discussions](https://github.com/github/docs/discussions). If not, open a new discussion!
-
-While you're there, we'd appreciate any help answering questions you feel knowledgeable about.
-
-### Failed status checks
-If your pull request has failing status checks, [Troubleshooting](/contributing/troubleshooting.md) will walk you through some of the possible reasons.
-
-## Draft pull requests
-Do not review any [draft PRs](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests), they're not ready! The docs team uses draft PRs to work on projects over time. When the PR is ready for feedback, we'll change the state from draft to ready for review.
-
 ## Reviewing
 We (usually the docs team, but sometimes GitHub product managers, engineers, or supportocats too!) review every single PR. The purpose of reviews is to create the best content we can for people who use GitHub.
 

README.md

@@ -2,7 +2,7 @@
 
 This repository contains the documentation website code and Markdown source files for docs.github.com.
 
-GitHub's Docs team works on pre-production content in a private repo that regularly syncs with this public repo. 
+GitHub's Docs team works on pre-production content in a private repo that regularly syncs with this public repo.
 
 In this article:
 - [Contributing](#contributing)
@@ -12,15 +12,33 @@ In this article:
 
 ## Contributing
 
-:memo: To find out how you can best contribute to GitHub's product documentation, see the [CONTRIBUTING](/CONTRIBUTING.md) guide.
+### Start contributing right now:
 
-:mega: If you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
+We accept a lot of [different contributions](CONTRIBUTING.md/#types-of-contributions-memo), including some that don't require you to write a single line of code.
 
-:beetle: If you've found a problem, you can open an issue using a [template](https://github.com/github/docs/issues/new/choose).
+#### Click **make a contribution** from docs
 
-:question: If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
+As you're using the GitHub Docs, you may find something in an article that you'd like to add to, update, or change. Click on **make a contribution** to navigate directly to that article in the codebase, so that you can begin making your contribution.
 
-:yellow_heart: We do not accept pull requests for translated content - see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
+<img src="./assets/images/contribution_cta.png" width="400">
+
+#### Open an issue
+
+If you've found a problem, you can open an issue using a [template](https://github.com/github/docs/issues/new/choose).
+
+#### Join us in discussions
+
+We use GitHub Discussions to talk about all sorts of topics related to documentation and this site. For example: if you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
+
+#### And that's it!
+That's how you can get started easily as a member of the GitHub Documentation community. :sparkles:
+
+If you want to know more, or you're making a more complex contribution, check out [Getting Started with Contributing](/CONTRIBUTING.md).
+
+There are a few more things to know when you're getting started with this repo:
+
+1. If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
+2. We do not accept pull requests for translated content - see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
 
 ## READMEs
 
@@ -99,4 +117,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- prettier-ignore-end -->
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!