Improve the explanation and linking of the Oauth docs.

6 files changed, 18 insertions, 9 deletions

diff --git a/doc/README.md b/doc/README.md
index 932e90e359a..59cfe1bb11a 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -10,6 +10,7 @@
 - [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects.
 - [Web hooks](web_hooks/web_hooks.md) Let GitLab notify you when new code has been pushed to your project.
 - [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN.
+- [OAuth2 provider](integration/oauth_provider.md) to allow you to login to other applications from GitLab.
 
 ## Administrator documentation
 
diff --git a/doc/api/README.md b/doc/api/README.md
index 8cbba8598d5..dec530d0b81 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -22,6 +22,7 @@
 ## Clients
 
 Find API Clients for GitLab [on our website](https://about.gitlab.com/applications/#api-clients).
+You can use [GitLab as an OAuth2 client](oauth2.md) to make API calls.
 
 ## Introduction
 
@@ -67,7 +68,7 @@ curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
 curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
 ```
 
-Read more about [OAuth2 in GitLab](oauth2.md).
+Read more about [GitLab as an OAuth2 client](oauth2.md).
 
 ## Status codes
 
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
index 7bb391054ce..d416a826f79 100644
--- a/doc/api/oauth2.md
+++ b/doc/api/oauth2.md
@@ -1,14 +1,17 @@
-# OAuth2 authentication
+# GitLab as an OAuth2 client
 
-OAuth2 is a protocol that enables us to get access to private details of user's account without getting its password. 
+This document is about using other OAuth authentication service providers to sign into GitLab.
+If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [Oauth2 provider documentation](../integration/oauth_provider.md).
 
-Before using the OAuth2 you should create an application in user's account. Each application getting unique App ID and App Secret parameters. You should not share them.
+OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password. 
+
+Before using the OAuth2 you should create an application in user's account. Each application gets a unique App ID and App Secret parameters. You should not share these.
 
 This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
 
 ## Web Application Flow
 
-This flow is using for authentication from third-party web sites and probably is most used. 
+This flow is using for authentication from third-party web sites and is probably used the most. 
 It basically consists of an exchange of an authorization token for an access token. For more detailed info, check out the [RFC spec here](http://tools.ietf.org/html/rfc6749#section-4.1)
 
 This flow consists from 3 steps.
diff --git a/doc/integration/README.md b/doc/integration/README.md
index 1fc8ab997ec..e5f33d8deed 100644
--- a/doc/integration/README.md
+++ b/doc/integration/README.md
@@ -8,9 +8,8 @@ See the documentation below for details on how to configure these services.
 - [LDAP](ldap.md) Set up sign in via LDAP
 - [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab, and Google via OAuth.
 - [Slack](slack.md) Integrate with the Slack chat service
-- [OAuth2 provider](oauth_provider.md) OAuth2 application creation
 
-Jenkins support is [available in GitLab EE](http://doc.gitlab.com/ee/integration/jenkins.html).
+GitLab Enterprise Edition contains [advanced JIRA support](http://doc.gitlab.com/ee/integration/jira.html) and [advanced Jenkins support](http://doc.gitlab.com/ee/integration/jenkins.html).
 
 ## Project services
 
diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md
index 53d6898b6e8..96755707dee 100644
--- a/doc/integration/external-issue-tracker.md
+++ b/doc/integration/external-issue-tracker.md
@@ -8,6 +8,8 @@ GitLab has a great issue tracker but you can also use an external issue tracker
 
 ![Jira screenshot](jira-integration-points.png)
 
+GitLab Enterprise Edition contains [advanced JIRA support](http://doc.gitlab.com/ee/integration/jira.html).
+
 ## Configuration
 
 ### Project Service
@@ -23,7 +25,6 @@ Fill in the required details on the page:
 * `issues_url` The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the url. This id is used by GitLab as a placeholder to replace the issue number.
 * `new_issue_url` This is the URL to create a new issue in Redmine for the project linked to this GitLab project.
 
-
 ### Service Template
 
 It is necessary to configure the external issue tracker per project, because project specific details are needed for the integration with GitLab.
diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md
index 5fdb74a43df..192c321f712 100644
--- a/doc/integration/oauth_provider.md
+++ b/doc/integration/oauth_provider.md
@@ -1,4 +1,8 @@
-## GitLab as OAuth2 provider
+## GitLab as OAuth2 authentication service provider
+
+This document is about using GitLab as an OAuth authentication service provider to sign into other services.
+If you want to use other OAuth authentication service providers to sign into GitLab please see the [OAuth2 client documentation](../api/oauth2.md)
+
 OAuth2 provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. Or you can allow users to sign in to your application with their GitLab.com account.
 In fact OAuth allows to issue access token to third-party clients by an authorization server, 
 with the approval of the resource owner, or end-user.