Merge branch 'eread/document-jira-integration-types' into 'master'

Add integration types table and polish some content

See merge request gitlab-org/gitlab!51867

doc/user/project/integrations/jira_cloud_configuration.md

@@ -4,10 +4,10 @@ group: Ecosystem
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Creating an API token in Jira Cloud
+# Create an API token in Jira on Atlassian cloud
 
-An API token is needed when integrating with Jira Cloud, follow the steps
-below to create one:
+For [integrations with Jira](jira.md), an API token is needed when integrating with Jira
+on Atlassian cloud. To create an API token:
 
 1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address.
 
@@ -17,10 +17,11 @@ below to create one:
 
 1. Click **Create API token**.
 
-![Jira API token](img/jira_api_token_menu.png)
+   ![Jira API token](img/jira_api_token_menu.png)
 
-![Jira API token](img/jira_api_token.png)
+1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configure-gitlab).
 
-1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab).
+   ![Jira API token](img/jira_api_token.png)
 
-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.
+The Jira configuration is complete. You need the newly created token, and the associated email
+address, when [configuring GitLab](jira.md#configure-gitlab).

doc/user/project/integrations/jira_integrations.md

@@ -6,26 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Jira integrations
 
-## Introduction
+GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira).
 
-GitLab Issues are a tool for discussing ideas and planning and tracking work. However, your organization may already use Jira for these purposes, with
-extensive, established data and business processes they rely on.
+[Issues](../issues/index.md) are a tool for discussing ideas, and planning and tracking work.
+However, your organization may already use Jira for these purposes, with extensive, established data
+and business processes they rely on.
 
-Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using the GitLab Jira integrations.
+Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work
+exclusively in GitLab, you can also continue to use Jira by using the GitLab Jira integrations.
 
-## Integrations
+## Integration types
 
-The following Jira integrations allow different types of cross-referencing between GitLab activity and Jira issues, with additional features:
+There are two different Jira integrations that allow different types of cross-referencing between
+GitLab activity and Jira issues, with additional features:
 
-- [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud.
-- [**Jira development panel integration**](../../../integration/jira_development_panel.md) - This connects all GitLab projects under a specified group or personal namespace.
-  - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app).
-  - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration).
+- [Jira integration](jira.md), built in to GitLab. In a given GitLab project, it can be configured
+  to connect to any Jira instance, either hosted by you or hosted in
+  [Atlassian cloud](https://www.atlassian.com/cloud).
+- [Jira development panel integration](../../../integration/jira_development_panel.md). Connects all
+  GitLab projects under a specified group or personal namespace.
 
-### Feature comparison
+Jira development panel integration configuration depends on whether:
+
+- You're using GitLab.com or a self-managed GitLab instance.
+- You're using Jira on [Atlassian cloud](https://www.atlassian.com/cloud) or on your own server.
+
+| You use Jira on: | For the Jira development panel integration, GitLab.com customers need:                                                                                                                                                        | For the Jira development panel integration, GitLab self-managed customers need:                                                                                                                                                                                               |
+|:-------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Atlassian cloud    | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See a [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/268278) for more information.            |
+| Your own server    | The [Jira DVCS connector](../../../integration/jira_development_panel.md).                                                                                                                                                      | The [Jira DVCS connector](../../../integration/jira_development_panel.md).                                                                                                                                                                                                      |
+
+NOTE:
+DVCS means distributed version control system.
+
+## Feature comparison
+
+The integration to use depends on the capabilities your require. You can install both at the same
+time.
 
 | Capability                                                                  | Jira integration                                                                                                                                              | Jira Development Panel integration                                                                                     |
-|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+|:----------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------|
 | Mention of Jira issue ID in GitLab is automatically linked to that issue    | Yes                                                                                                                                                           | No                                                                                                                     |
 | Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue  | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel                                                                                  |
 | Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab.                  | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. |

doc/user/project/integrations/jira_server_configuration.md

@@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Create Jira Server username and password
 
-We need to create a user account in Jira to have access to all projects that
-need to integrate with GitLab.
+For [integrations with Jira](jira.md), you must create a user account in Jira to have access to
+all projects that need to integrate with GitLab.
 
 The Jira user account created for the integration must have write access to
 your Jira projects.
@@ -65,4 +65,4 @@ member of a new group named `gitlab-developers`:
    ![Jira group access](img/jira_group_access.png)
 
 The Jira configuration is complete. Write down the new Jira username and its
-password, as you'll need them when [configuring GitLab in the next section](jira.md#configuring-gitlab).
+password, as you need them when [configuring GitLab](jira.md#configure-gitlab).