diff --git a/doc/api/services.md b/doc/api/services.md
index c7f537aceb652a3fc72b687f4f1dde00049ad30b..a5d733fe6c7ebebc6e2833bc9087b42e41225c0a 100644
--- a/doc/api/services.md
+++ b/doc/api/services.md
@@ -465,10 +465,10 @@ GET /projects/:id/services/jira
 
 Set JIRA service for a project.
 
->**Note:**
-Setting `project_url`, `issues_url` and `new_issue_url` will allow a user to
-easily navigate to the JIRA issue tracker. See the [integration doc][jira-doc]
-for details.
+>**Notes:**
+- Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and
+  `project_url` are replaced by `project_key`, `url`.  If you are using an
+  older version, [follow this documentation][old-jira-api].
 
 ```
 PUT /projects/:id/services/jira
@@ -477,11 +477,8 @@ PUT /projects/:id/services/jira
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `active`        | boolean| no  | Enable/disable the JIRA service. |
-| `project_url`   | string | yes | The URL to the JIRA project which is being linked to this GitLab project. It is of the form: `https://<jira_host_url>/issues/?jql=project=<jira_project>`. |
-| `issues_url`    | string | yes | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. It is of the form: `https://<jira_host_url>/browse/:id`. Leave `:id` as-is, it gets replaced by GitLab at runtime.|
-| `new_issue_url` | string | yes | This is the URL to create a new issue in JIRA for the project linked to this GitLab project, and it is of the form: `https://<jira_host_url>/secure/CreateIssue.jspa` |
-| `api_url`       | string | yes | The base URL of the JIRA API. It may be omitted, in which case GitLab will automatically use API version `2` based on the `project url`. It is of the form: `https://<jira_host_url>/rest/api/2`. |
-| `description`   | string | no  | A name for the issue tracker. |
+| `url`           | string | yes | The URL to the JIRA project which is being linked to this GitLab project, e.g., `https://jira.example.com`. |
+| `project_key`   | string | yes | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. |
 | `username`      | string | no  | The username of the user created to be used with GitLab/JIRA. |
 | `password`      | string | no  | The password of the user created to be used with GitLab/JIRA. |
 | `jira_issue_transition_id` | string | no | The ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot][trans]). By default, this ID is set to `2`. |
@@ -670,3 +667,4 @@ GET /projects/:id/services/teamcity
 ```
 
 [jira-doc]: ../project_services/jira.md
+[old-jira-api]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/doc/api/services.md#jira
diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md
index e537a24028cad6a958f094e7579cd8ddffa5e9b7..366e4b2d3067229640de28c3809fbb7c9f87ba29 100644
--- a/doc/project_services/jira.md
+++ b/doc/project_services/jira.md
@@ -97,7 +97,7 @@ in the table below.
 | Field | Description |
 | ----- | ----------- |
 | `URL` | The base URL to the JIRA project which is being linked to this GitLab project. E.g., `https://jira.example.com`. |
-| `Project key` | The short, the identifier for your JIRA project, all uppercase. |
+| `Project key` | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. |
 | `Username` | The user name created in [configuring JIRA step](#configuring-jira). |
 | `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). |
 | `JIRA issue transition` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). |
@@ -121,7 +121,7 @@ ID in GitLab commits and merge requests.
 When GitLab project has JIRA issue tracker configured and enabled, mentioning
 JIRA issue in GitLab will automatically add a comment in JIRA issue with the
 link back to GitLab. This means that in comments in merge requests and commits
-referencing an issue, eg. `PROJECT-7`, will add a comment in JIRA issue in the
+referencing an issue, e.g., `PROJECT-7`, will add a comment in JIRA issue in the
 format:
 
 ```
@@ -150,11 +150,11 @@ the transition ID was set up correctly).
 There are currently three trigger words, and you can use either one to achieve
 the same goal:
 
-- `Resolves GITLAB-1`
-- `Closes GITLAB-1`
-- `Fixes GITLAB-1`
+- `Resolves PROJECT-1`
+- `Closes PROJECT-1`
+- `Fixes PROJECT-1`
 
-- where `GITLAB-1` the issue ID of the JIRA project.
+where `PROJECT-1` is the issue ID of the JIRA project.
 
 ### JIRA issue closing example