Merge branch 'bbodenmiller-master-patch-01469' into 'master'

Clarify Jira docs

See merge request gitlab-org/gitlab!69918

doc/integration/jira/development_panel.md

@@ -65,7 +65,7 @@ For an overview of how to configure Jira Development panel integration, see
 [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M).
 
 To simplify administration, we recommend that a GitLab group maintainer or group owner
-(or instance administrator in the case of self-managed GitLab) set up the integration.
+(or, if possible, instance administrator in the case of self-managed GitLab) set up the integration.
 
 | Jira usage | GitLab.com customers need | GitLab self-managed customers need |
 |------------|---------------------------|------------------------------------|
@@ -89,10 +89,6 @@ This integration is not supported on GitLab instances under a
 [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab).
 For example, `http://example.com/gitlab`.
 
-## Related topics
-
-- [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in Jira
-
 ## Troubleshooting
 
 ### Cookies for Oracle's Access Manager

doc/integration/jira/dvcs.md

@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 Use the Jira DVCS (distributed version control system) connector if you self-host
 your Jira instance, and you want to sync information
-between GitLab and Jira. If you use Jira Cloud and GitLab.com, you should use the
+between GitLab and Jira. If you use Jira Cloud, you should use the
 [GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the
 DVCS connector.
 
@@ -16,8 +16,8 @@ When you configure the Jira DVCS connector, make sure your GitLab and Jira insta
 are accessible.
 
 - **Self-managed GitLab**: Your GitLab instance must be accessible by Jira.
-- **Jira Cloud**: Your instance must be accessible through the internet.
 - **Jira Server**: Your network must allow access to your instance.
+- **Jira Cloud**: Your instance must be accessible through the internet.
 
 ## Smart commits
 
@@ -64,11 +64,12 @@ you can still perform multiple actions in a single commit:
 
 We recommend you create and use a `jira` user in GitLab, and use the account
 only for integration work. A separate account ensures regular account
-maintenance does not affect your integration.
+maintenance does not affect your integration. If a `jira` user is not feasible,
+you can set up this integration with your own account instead.
 
 1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to
-   use to connect to GitLab. For Jira to access all projects,
-   this user must have an [Administrator](../../user/permissions.md) role.
+   use to connect to GitLab. This user must be added to each project you want Jira to have access to,
+   or have an [Administrator](../../user/permissions.md) role to access all projects.
 1. Sign in as the `jira` user.
 1. In the top right corner, click the account's avatar, and select **Edit profile**.
 1. On the left sidebar, select **Applications**.
@@ -105,9 +106,9 @@ it completes, refreshes every 60 minutes:
    - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**.
 1. For **Team or User Account**, enter either:
    - *For Jira versions 8.14 and later:*
-      - The relative path of a top-level GitLab group that you have access to.
+      - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to.
    - *For Jira versions 8.13 and earlier:*
-      - The relative path of a top-level GitLab group that you have access to.
+      - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to.
       - The relative path of your personal namespace.
 
 1. In the **Host URL** field, enter the URI appropriate for your version of GitLab,

doc/integration/jira/index.md

@@ -26,9 +26,7 @@ The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be).
 
-To set up the integration, [configure the project settings](configure.md) in GitLab.
-You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration),
-and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration).
+To set up the integration, [configure the settings](configure.md) in GitLab.
 
 ### Jira development panel integration
 
@@ -37,12 +35,9 @@ connects all GitLab projects under a group or personal namespace. When configure
 relevant GitLab information, including related branches, commits, and merge requests,
 displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/).
 
-To set up the Jira development panel integration:
-
-- *If your installation uses Jira Cloud,* use the
-  [GitLab.com for Jira Cloud app](connect-app.md).
-- *If either your Jira or GitLab installation is self-managed,* use the
-  [Jira DVCS (distributed version control system) connector](dvcs.md).
+To set up the Jira development panel integration, use the GitLab.com for Jira Cloud app
+or the Jira DVCS (distributed version control system) connector,
+[depending on your installation](development_panel.md#configure-the-integration).
 
 ### Direct feature comparison