Merge branch '324250-aqualls-polish' into 'master'

Tidy up two Jira configuration pages

See merge request gitlab-org/gitlab!57522

doc/integration/jira/jira_cloud_configuration.md

@@ -6,22 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Create an API token in Jira on Atlassian cloud **(FREE)**
 
-For [integrations with Jira](../../user/project/integrations/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.
-
-   NOTE:
-   It is important that the user associated with this email address has *write* access
-   to projects in Jira.
-
-1. Click **Create API token**.
-
-   ![Jira API token](../../user/project/integrations/img/jira_api_token_menu.png)
-
-1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](../../user/project/integrations/jira.md#configure-gitlab).
-
-   ![Jira API token](../../user/project/integrations/img/jira_api_token.png)
-
-The Jira configuration is complete. You need the newly created token, and the associated email
-address, when [configuring GitLab](../../user/project/integrations/jira.md#configure-gitlab).
+You need an API token to [integrate with Jira](../../user/project/integrations/jira.md)
+on Atlassian cloud. To create the API token:
+
+1. Sign in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens)
+   with your email address. Use an account with *write* access to Jira projects.
+1. Go to **Settings > API tokens**.
+1. Select **Create API token** to display a modal window with an API token.
+1. To copy the API token, select **Copy to clipboard**, or select **View** and write
+   down the new API token. You need this value when you
+   [configure GitLab](../../user/project/integrations/jira.md#configure-gitlab).
+
+You need the newly created token, and the email
+address you used when you created it, when you
+[configure GitLab](../../user/project/integrations/jira.md#configure-gitlab).

doc/integration/jira/jira_server_configuration.md

@@ -4,65 +4,80 @@ 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
 ---
 
-# Create Jira Server username and password **(FREE)**
+# Jira Server credentials **(FREE)**
 
-For [integrations with Jira](../../user/project/integrations/jira.md), you must create a user account in Jira to have access to
-all projects that need to integrate with GitLab.
+To [integrate Jira with GitLab](../../user/project/integrations/jira.md), you must
+create a Jira user account for your Jira projects to access projects in GitLab.
+This Jira user account must have write access to your Jira projects. To create the
+credentials, you must:
 
-The Jira user account created for the integration must have write access to
-your Jira projects.
+1. [Create a Jira Server user](#create-a-jira-server-user).
+1. [Create a Jira Server group](#create-a-jira-server-group) for the user to belong to.
+1. [Create a permission scheme for your group](#create-a-permission-scheme-for-your-group).
 
-As an example, the following process creates a user named `gitlab` and that's a
-member of a new group named `gitlab-developers`:
+## Create a Jira Server user
 
-1. Sign in to your Jira instance as an administrator, and
-   then go to the gear icon and select **User Management**.
+This process creates a user named `gitlab` and adds it to a new group named `gitlab-developers`:
 
-   ![Jira user management link](../../user/project/integrations/img/jira_user_management_link.png)
+1. Sign in to your Jira instance as an administrator.
+1. In the upper right corner of the top menu, go to the gear icon and
+   select **User Management**.
+1. Create a new user account (`gitlab`) with write access to
+   projects in Jira.
+   - **Email address**: Jira requires a valid email address, and sends a verification
+     email, which you need to set up the password.
+   - **Username**: Jira creates the username by using the email prefix. You can change
+     this username later.
+   - **Password**: You must create a password, because the GitLab integration doesn't
+     support SSO, such as SAML. To create the password, visit the user profile, look up
+     the username, and set a password.
+1. Select **Create user**.
 
-1. Create a new user account (for example, `gitlab`) with write access to
-   projects in Jira. Enter the user account's name and a valid e-mail address,
-   because Jira sends a verification email to set up the password.
+After you create the user, create a group for it.
 
-   Jira creates the username by using the email prefix. You can change the
-   username later, if needed. The GitLab integration doesn't support SSO (such
-   as SAML). You need to create an HTTP basic authentication password. You can
-   do this by visiting the user profile, looking up the username, and setting a
-   password.
+## Create a Jira Server group
 
-   ![Jira create new user](../../user/project/integrations/img/jira_create_new_user.png)
+After you [create a Jira Server user](#create-a-jira-server-user), you can create a
+group to assign permissions to the user:
 
+1. Sign in to your Jira instance as an administrator.
+1. In the upper right corner of the top menu, go to the gear icon and
+   select **User Management**.
 1. From the sidebar, select **Groups**.
 
    ![Jira create new user](../../user/project/integrations/img/jira_create_new_group.png)
 
 1. In the **Add group** section, enter a **Name** for the group (for example,
    `gitlab-developers`), and then select **Add group**.
-
-1. Add the `gitlab` user to the `gitlab-developers` group by selecting **Edit members**.
+1. To add the `gitlab` user to the `gitlab-developers` group, select **Edit members**.
    The `gitlab-developers` group should be listed in the leftmost box as a
-   selected group. In the **Add members to selected group(s)** area, enter `gitlab`.
+   selected group.
+1. In the **Add members to selected group(s)** area, enter `gitlab`.
+1. Select **Add selected users**.
+Jira saves your selection, and `gitlab` should appear in the **Group member(s)**
+area.
 
-   ![Jira add user to group](../../user/project/integrations/img/jira_add_user_to_group.png)
+![Jira added user to group](../../user/project/integrations/img/jira_added_user_to_group.png)
 
-   Select **Add selected users**, and `gitlab` should appear in the **Group member(s)**
-   area. This membership is saved automatically.
+Next, create a permission scheme for your group.
 
-   ![Jira added user to group](../../user/project/integrations/img/jira_added_user_to_group.png)
+## Create a permission scheme for your group
 
-1. To give the newly-created group 'write' access, you must create a permission
-   scheme. To do this, in the admin menu, go to the gear icon and select **Issues**.
+After creating the group in Jira, grant permissions to the group by creating a permission scheme:
 
+1. Sign in to your Jira instance as an administrator.
+1. In the upper right corner of the top menu, go to the gear icon and
+   select **Issues**.
 1. From the sidebar, select **Permission Schemes**.
-
 1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a
    **Description**, and then select **Add**.
-
 1. In the permissions scheme list, locate your new permissions scheme, and
-   select **Permissions**. Next to **Administer Projects**, select **Edit**. In
+   select **Permissions**.
+1. Next to **Administer Projects**, select **Edit**. In
    the **Group** list, select `gitlab-developers`.
 
    ![Jira group access](../../user/project/integrations/img/jira_group_access.png)
 
-The Jira configuration is complete. Write down the new Jira username and its
-password, as you need them when [configuring GitLab](../../user/project/integrations/jira.md#configure-gitlab).
+Write down the new Jira username and its
+password, as you need them when
+[configuring GitLab](../../user/project/integrations/jira.md#configure-gitlab).