Merge branch 'docs-update-jira-integration' into 'master'

Docs: Update Jira integration

See merge request gitlab-org/gitlab-ce!29997

doc/user/project/integrations/jira.md

@@ -39,21 +39,17 @@ a GitLab project with any single Jira project.
 If you have one Jira instance, you can pre-fill the settings page with a default
 template. See the [Services Templates][services-templates] docs.
 
-Configuration happens via user name and password. Connecting to a Jira Server
-via CAS is not possible.
-
-In order to enable the Jira service in GitLab, you need to first configure the
-project in Jira and then enter the correct values in GitLab.
+In order to enable the Jira service in GitLab, you need to first configure the project in Jira and then enter the correct values in GitLab.
 
 ### Configuring Jira
 
-When connecting to **Jira Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step:
+#### Jira Server
 
-- [Setting up a user in Jira Server](jira_server_configuration.md)
+When connecting to **Jira Server**, which supports basic authentication, a **username and password** are required. Note that connecting to a Jira server via CAS is not possible. [Set up a user in Jira Server](jira_server_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab).
 
-When connecting to **Jira Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step:
+#### Jira Cloud
 
-- [Setting up a user in Jira Cloud](jira_cloud_configuration.md)
+When connecting to **Jira Cloud**, which supports authentication via API token, an **email and API token**, are required. [Set up a user in Jira Cloud](jira_cloud_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab).
 
 ### Configuring GitLab
 
@@ -68,7 +64,7 @@ When connecting to **Jira Cloud**, which supports authentication via API token,
 >   to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with
 >   a value of `fromDialog`.
 
-To enable Jira integration in a project, navigate to the
+To enable the Jira integration in a project, navigate to the
 [Integrations page](project_services.md#accessing-the-project-services), click
 the **Jira** service, and fill in the required details on the page as described
 in the table below.
@@ -127,6 +123,12 @@ ENTITY_TITLE
 
 ![example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
 
+For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID:
+
+```bash
+git commit -m "PROJECT-1 Fix spelling and grammar"
+```
+
 ### Closing Jira Issues
 
 Jira issues can be closed directly from GitLab by using trigger words in
@@ -142,7 +144,7 @@ the same goal:
 - `Closes PROJECT-1`
 - `Fixes PROJECT-1`
 
-where `PROJECT-1` is the issue ID of the Jira project.
+where `PROJECT-1` is the ID of the Jira issue.
 
 > **Notes:**
 >
@@ -174,8 +176,6 @@ with a link to the commit that resolved the issue.
 
 ![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
 
-![The GitLab integration creates a comment and a link on Jira issue.](img/jira_service_close_comment.png)
-
 ## Troubleshooting
 
 If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured.

doc/user/project/integrations/jira_cloud_configuration.md

@@ -3,16 +3,18 @@
 An API token is needed when integrating with Jira Cloud, follow the steps
 below to create one:
 
-1. Log in to <https://id.atlassian.com> with your email.
-1. **Click API tokens**, then **Create API token**.
+1. Log in to <https://id.atlassian.com/manage/api-tokens> with your email address.
+
+   NOTE: **Note**
+   It is important that the user associated with this email address has *write* access
+   to projects in Jira.
+
+2. Click **Create API token**.
 
 ![Jira API token](img/jira_api_token_menu.png)
 
 ![Jira API token](img/jira_api_token.png)
 
-1. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab).
-
-NOTE: **Note**
-It is important that the user associated with this email has 'write' access to projects in Jira.
+1. Click **Copy to clipboard**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab).
 
-The Jira configuration is complete. You are going to need this newly created token and the email you used to log in, when [configuring GitLab in the next section](jira.md#configuring-gitlab).
+The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section.