diff --git a/doc/api/README.md b/doc/api/README.md
index 3a6c7b7682a..dece3e23619 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -1,10 +1,8 @@
 # Gitlab API
 
-All API requests require authentication. You need to pass `private_token` parameter to authenticate.
+All API requests require authentication. You need to pass a `private_token` parameter to authenticate. You can find or reset your private token in your profile.
 
-To get or reset your token visit your profile.
-
-If no or invalid `private_token` provided error message will be returned with status code 401:
+If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401:
 
 ```json
 {
@@ -12,10 +10,9 @@ If no or invalid `private_token` provided error message will be returned with st
 }
 ```
 
-API requests should be prefixed with `api` and the API version.
-API version is equal to Gitlab major version number and defined in `lib/api.rb`.
+API requests should be prefixed with `api` and the API version. The API version is equal to the Gitlab major version number, which is defined in `lib/api.rb`.
 
-Example of valid API request:
+Example of a valid API request:
 
 ```
 GET http://example.com/api/v2/projects?private_token=QVy1PB7sTxfy4pqfZM1U
diff --git a/doc/api/projects.md b/doc/api/projects.md
index b0c1e65709c..e029522be18 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -1,6 +1,6 @@
 ## List projects
 
-Get a list of authenticated user's projects.
+Get a list of projects owned by the authenticated user.
 
 ```
 GET /projects
@@ -55,7 +55,7 @@ GET /projects
 
 ## Single project
 
-Get an authenticated user's project.
+Get a specific project, identified by project ID, which is owned by the authentication user.
 
 ```
 GET /projects/:id
@@ -109,7 +109,7 @@ found` on fail.
 
 ## Project repository branches
 
-Get a list of project repository branches sorted by name alphabetically.
+Get a list of repository branches from a project, sorted by name alphabetically.
 
 ```
 GET /projects/:id/repository/branches
@@ -186,7 +186,7 @@ Parameters:
 
 ## Project repository tags
 
-Get a list of project repository tags sorted by name in reverse alphabetical order.
+Get a list of repository tags from a project, sorted by name in reverse alphabetical order.
 
 ```
 GET /projects/:id/repository/tags
@@ -237,3 +237,4 @@ Parameters:
 + `filepath` (required) - The path the file 
 
 Will return the raw file contents.
+