Merge pull request #1943 from github/docs-changes

Documentation updates

docs/contributing/cloning-a-repository-to-visual-studio.md

@@ -1,19 +0,0 @@
-# Cloning a repository to Visual Studio
-
-After you provide your GitHub or GitHub Enterprise credentials to GitHub for Visual Studio, the extension automatically detects the personal and organization repositories you have access to on your account.
-
-1. Open **Team Explorer** by clicking on its tab next to *Solution Explorer*, or via the *View* menu.
-2. Click the **Manage Connections** toolbar button.
-
-![Location of the manage connections toolbar button in Team Explorer](images/manage-connections.png)
-
-3. Next to the account you want to clone from, click **Clone**.
-
-![Clone button in the GitHub section of Team Explorer](images/clone-link.png)
-
-4. In the list of repositories, click the repository you'd like to clone.
-
-![List of GitHub repositories that can be cloned inside a dialog](images/clone-dialog.png)
-
-5. If desired, change the local path where the repository will be cloned into, or leave the default as-is. Click **Clone**.
-6. In Team Explorer, under the list of repositories, locate the repository and double-click to open the project in Visual Studio.

docs/contributing/creating-gists.md

@@ -1,23 +0,0 @@
-# Creating gists
-
-GitHub for Visual Studio enables easy creation of gists directly from the Visual Studio Editor.
-
-1. [Sign in](../getting-started/authenticating-to-github.md) to GitHub.
-
-2. Open a file in the Visual Studio text editor.
-
-3. Select the section of text that you want to create a gist from.
-
-4. Right click and select **Create a GitHub Gist** from the **GitHub** submenu.
-
-   ![Location of Create A GitHub Gist in the GitHub submenu](images/create-gist-menu.png)
-
-5. In the **Create a GitHub Gist** dialog, check that the filename is correct and optionally add a description.
-
-   ![GitHub Gist creation dialog window](images/create-gist-dialog.png)
-
-6. If you want the gist to be private, check the **Private Gist** checkbox.
-
-7. Click **Create**.
-
-8. Once the gist is created it will be opened in your browser.

docs/contributing/viewing-the-pull-requests-for-a-repository.md

@@ -1,15 +0,0 @@
-# Viewing the pull requests for a repository
-
-GitHub for Visual Studio exposes the pull requests for the current repository and lets you create new pull requests and review pull requests from other contributors.
-
-1. [Sign in](../getting-started/authenticating-to-github.md) to GitHub.
-2. Open a solution in a GitHub repository.
-3. Open **Team Explorer** and click the **Pull Requests** button to open the **GitHub** pane.
-![Pull Requests button in the Team Explorer pane](images/pull-requests-button2.png)
-4. The open pull requests will be displayed.
-![Pull requests in the GitHub pane](images/pull-request-list.png)
-5. Change the Open/Closed filter by clicking the **Open** link and selecting the filter you want to use from the dropdown.
-6. Filter pull requests by Assignee by clicking the **Assignee** link and selecting the assignee you want to view from the dropdown.
-7. Filter pull requests by Author by clicking the **Author** link and selecting the author you want to view from the dropdown.
-8. Click on a pull request title to [view the pull request details and review the pull request](review-a-pull-request-in-visual-studio.md)
-9. Click on the **Create New** link to [create a pull request from the current branch](sending-a-pull-request.md)

docs/using/cloning-a-repository-to-visual-studio.md

@@ -0,0 +1,39 @@
+# Cloning a repository to Visual Studio
+
+After you provide your GitHub or GitHub Enterprise credentials to GitHub for Visual Studio, the extension automatically detects the personal, collaborator and organization repositories you have access to on your account.
+
+## Opening the clone dialog 
+
+### From **Team Explorer**
+
+Open **Team Explorer** by clicking on its tab next to *Solution Explorer*, or via the *View* menu.
+Click the **Manage Connections** toolbar button.
+
+![Location of the manage connections toolbar button in Team Explorer](images/manage-connections.png)
+
+Next to the account you want to clone from, click **Clone**.
+
+![Clone button in the GitHub section of Team Explorer](images/clone-link.png)
+
+### From the **Start Page**
+
+Using Visual Studio 2017, click the `GitHub` button on the `Start Page` to open the clone dialog. 
+
+
+### From the **File** menu
+
+Go to `File > Open > Open From GitHub...`
+
+
+## Clone repositories
+1. In the list of repositories, scroll until you find the repository you'd like to clone. You can also filter the repository results by using the *Filter* text box.
+
+![List of GitHub repositories that can be cloned inside a dialog](images/clone-dialog.png)
+
+In addition to using the list of personal, collaborator and organization repositories, you can use the URL tab to clone a public repository by its URL or using the repository owner and name.
+
+![List of GitHub repositories that can be cloned inside a dialog](images/clone-url-dialog.png)
+
+2. If desired, change the local path that the repository will be cloned into, or leave the default as-is.
+3. Once a repository is selected and the path is set, Click **Clone**.
+4. In Team Explorer, under the list of solutions, double-click on a solution to open it in Visual Studio.

docs/using/creating-gists.md

@@ -0,0 +1,26 @@
+# Creating gists
+
+With GitHub for Visual Studio, you can easily create gists directly from the editor.
+
+1. [Sign in](../getting-started/authenticating-to-github.md) to GitHub.
+
+2. Open a file in the Visual Studio text editor.
+
+3. Select the section of text that you want to create a gist from.
+
+4. Right click and select **Create a GitHub Gist** from the **GitHub** submenu to create the gist on GitHub.
+
+   ![Location of Create a GitHub Gist in the GitHub submenu](images/create-github-gist-menu.png)
+
+5. To create the gist on GitHub Enterprise select **Create an Enterprise Gist** option from the submenu.
+    ![Location of Create a Enterprise Gist in the GitHub submenu](images/create-enterprise-gist-menu.png)
+
+6. In the **Create a GitHub Gist** dialog, check that the filename is correct and optionally add a description.
+
+   ![GitHub Gist creation dialog window](images/create-gist-dialog.png)
+
+7. If you want the gist to be private, check the **Private Gist** checkbox.
+
+8. Click **Create**.
+
+9. Once the gist is created it will be opened in your browser.

docs/using/reviewing-a-pull-request-in-visual-studio.md

@@ -12,15 +12,21 @@ GitHub for Visual Studio provides facilities for reviewing a pull request direct
 
 ## Viewing a pull request
 
-The Pull Request Details view shows the current state of the pull request, including information about who created the pull request, the source and target branch, and the files changed.
+The Pull Request Details view shows the current state of the pull request, including:
+- information about who created the pull request
+- the source and target branch
+- a description of the pull request
+- reviewers and the status of their review
+- checks (if checks have been enabled for the repository)
+- the files changed
 
-![The details of a single pull request in the GitHub pane](images/pr-details.png)
+![The details of a single pull request in the GitHub pane](images/pr-detail-view.png)
 
 ## Checking out a pull request
 
 To check out the pull request branch, click the **Checkout [branch]** link where [branch] is the name of the branch that will be checked out.
 
-![Location of the checkout link in the GitHub pull request details page](images/pr-details-checkout-link.png)
+![Location of the checkout link in the GitHub pull request details page](images/pr-detail-view-checkout-branch.png)
 
 If the pull request is from a fork then a remote will be added to the forked repository and the branch checked out locally. This remote will automatically be cleaned up when the local branch is deleted.
 
@@ -46,6 +52,45 @@ You can add comments to a pull request directly from Visual Studio. When a file
 ![Hover over margin to see add comment icon](images/hover-to-add-comment.png)
 
 Then click the icon on the desired line and leave a comment.
-![Add a comment](images/add-comment.png)
+![Add a comment](images/add-review-comment.png)
 
-Existing comments left by you or other reviewers will also show up in this margin. Click the icon to open an inline conversation view from which you can review and reply to comments:
+To just comment on this one line, select **Add a single comment**. This will add the comment immediately.
+
+To start a review of the Pull Request and all its changes, select **Start a review**. This will add this comment as pending, and the comment will be submitted once the review is complete.
+
+#### Viewing comments
+
+Existing comments left by you or other reviewers will also show up in this margin. Click the icon to open an inline conversation view from which you can review and reply to comments.
+
+Single comments appear like this when viewed inline.
+![Single comment](images/single-comment.png)
+
+Review comments appear the same as single comments except for a Pending badge is added to the comment.
+![Single comment](images/pending-review-comment.png)
+
+#### Modifying Comments
+
+Single and review comments can either be edited or deleted.
+
+To edit a comment, press the pencil symbol to edit the comment and then select **Update comment** once finished.
+![Edit comment](images/edit-comment.png)
+
+To delete a comment, press the x symbol. A confirmation box to delete the comment will appear.
+![Delete comment](images/delete-comment.png)
+
+#### Submitting a review
+
+From the pull request details view you can go to the review summary and submit a review.
+
+If you have pending review comments you'll see the option **Continue your review**:
+![Continue review](images/continue-your-review.png)
+
+Otherwise you'll see an option to **Add your review**:
+
+![Add review](images/add-review.png)
+
+When you are redirected to the review summary view, leave a review summary and select **Submit review**.
+![Submit review](images/submit-review.png)
+
+The options available are to **Approve**, **Comment only** or **Request changes**.
+![Submit review options](images/submit-review-options.png)

docs/using/viewing-the-pull-requests-for-a-repository.md

@@ -0,0 +1,16 @@
+# Viewing the pull requests for a repository
+
+GitHub for Visual Studio exposes the pull requests for the current repository and lets you create new pull requests and review pull requests from other contributors.
+
+1. [Sign in](../getting-started/authenticating-to-github.md) to GitHub.
+2. Open a solution in a GitHub repository.
+3. Open **Team Explorer** and click the **Pull Requests** button to open the **GitHub** pane.
+![Pull Requests button in the Team Explorer pane](images/pull-requests-button2.png)
+4. The open pull requests will be displayed.
+![Pull requests in the GitHub pane](images/pull-request-list-view.png)
+5. Change the pull requests listed by clicking the **Open** link and selecting the filter you want to use from the dropdown with the options *Open/Closed/All*.
+![Pull requests status dropdown filter](images/pull-request-list-filter.png)
+6. Filter pull requests by author by clicking the person icon and selecting the user you want to view from the dropdown. You can also search for users from the dropdown.
+![Pull requests assignable user dropdown filter](images/pull-request-assignable-user.png)
+7. Double-click anywhere in the pull request item to [view the pull request details and review the pull request](reviewing-a-pull-request-in-visual-studio.md)
+8. Click on the **Create New** link to [create a pull request from the current branch](creating-a-pull-request.md)