Improve the explanation and linking of the Oauth docs.

2 files changed, 9 insertions, 5 deletions

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.