Merge branch 'msj-youtrack-docs' into 'master'

Make external issue tracker docs consistent

See merge request gitlab-org/gitlab!59996

doc/user/project/integrations/bugzilla.md

@@ -4,33 +4,55 @@ 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
 ---
 
-# Bugzilla Service **(FREE)**
+# Bugzilla service **(FREE)**
 
-Navigate to the [Integrations page](overview.md#accessing-integrations),
-select the **Bugzilla** service and fill in the required details as described
-in the table below.
+[Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing
+tool.
 
-| Field | Description |
-| ----- | ----------- |
-| `project_url`   | The URL to the project in Bugzilla which is being linked to this GitLab project. Note that the `project_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. |
-| `issues_url`    | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. |
-| `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. |
+You can configure Bugzilla as an
+[external issue tracker](../../../integration/external-issue-tracker.md) in GitLab.
 
-Once you have configured and enabled Bugzilla, you see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project.
+To enable the Bugzilla integration in a project:
 
-## Referencing issues in Bugzilla
+1. Go to the [Integrations page](overview.md#accessing-integrations).
+1. Select **Bugzilla**.
+1. Select the checkbox under **Enable integration**.
+1. Fill in the required fields:
 
-Issues in Bugzilla can be referenced in two alternative ways:
+   - **Project URL**: The URL to the project in Bugzilla.
+     For example, for a product named "Fire Tanuki":
+     `https://bugzilla.example.org/describecomponents.cgi?product=Fire+Tanuki`.
+   - **Issue URL**: The URL to view an issue in the Bugzilla project.
+     The URL must contain `:id`. GitLab replaces `:id` with the issue number (for example,
+     `https://bugzilla.example.org/show_bug.cgi?id=:id`, which becomes
+     `https://bugzilla.example.org/show_bug.cgi?id=123`).
+   - **New issue URL**: The URL to create a new issue in the linked Bugzilla project.
+     For example, for a project named "My Cool App":
+     `https://bugzilla.example.org/enter_bug.cgi#h=dupes%7CMy+Cool+App`.
 
-- `#<ID>` where `<ID>` is a number (example `#143`).
-- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is
-  then followed by capital letters, numbers or underscores, and `<ID>` is
-  a number (example `API_32-143`).
+1. Select **Save changes** or optionally select **Test settings**.
 
-We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked.
+After you configure and enable Bugzilla, a link appears on the GitLab
+project pages. This link takes you to the appropriate Bugzilla project.
 
-Please note that `<PROJECT>` part is ignored and links always point to the
-address specified in `issues_url`.
+You can also disable [GitLab internal issue tracking](../issues/index.md) in this project.
+Learn more about the steps and consequences of disabling GitLab issues in
+[Sharing and permissions](../settings/index.md#sharing-and-permissions).
+
+## Reference Bugzilla issues in GitLab
+
+You can reference issues in Bugzilla using:
+
+- `#<ID>`, where `<ID>` is a number (for example, `#143`).
+- `<PROJECT>-<ID>` (for example `API_32-143`) where:
+  - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores.
+  - `<ID>` is a number.
+
+The `<PROJECT>` part is ignored in links, which always point to the address specified in **Issue URL**.
+
+We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue
+trackers enabled. If you use the shorter format, and an issue with the same ID exists in the
+internal issue tracker, the internal issue is linked.
 
 ## Troubleshooting
 

doc/user/project/integrations/youtrack.md

@@ -4,40 +4,38 @@ 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
 ---
 
-# YouTrack Service **(FREE)**
+# YouTrack service **(FREE)**
 
-JetBrains [YouTrack](https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Documentation.html) is a web-based issue tracking and project management platform.
+JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project
+management platform.
 
-You can configure YouTrack as an [External Issue Tracker](../../../integration/external-issue-tracker.md) in GitLab.
+You can configure YouTrack as an
+[external issue tracker](../../../integration/external-issue-tracker.md) in GitLab.
 
-## Enable the YouTrack integration
+To enable the YouTrack integration in a project:
 
-To enable YouTrack integration in a project:
+1. Go to the [Integrations page](overview.md#accessing-integrations).
+1. Select **YouTrack**.
+1. Select the checkbox under **Enable integration**.
+1. Fill in the required fields:
+   - **Project URL**: The URL to the project in YouTrack.
+   - **Issue URL**: The URL to view an issue in the YouTrack project.
+     The URL must contain `:id`. GitLab replaces `:id` with the issue number.
+1. Select **Save changes** or optionally select **Test settings**.
 
-1. Navigate to the project's **Settings > [Integrations](overview.md#accessing-integrations)** page.
-1. Click the **YouTrack** service, ensure it's active, and enter the required details on the page as described in the table below.
+After you configure and enable YouTrack, a link appears on the GitLab
+project pages. This link takes you to the appropriate YouTrack project.
 
-   | Field           | Description                                                                                                                                                                                                 |
-   |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-   | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project.                                                                                                                                |
-   | **Issues URL**  | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. |
+You can also disable [GitLab internal issue tracking](../issues/index.md) in this project.
+Learn more about the steps and consequences of disabling GitLab issues in
+[Sharing and permissions](../settings/index.md#sharing-and-permissions).
 
-1. Click the **Save changes** button.
+## Reference YouTrack issues in GitLab
 
-Once you have configured and enabled YouTrack, you see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project.
+You can reference issues in YouTrack using `<PROJECT>-<ID>` (for example `YT-101`, `Api_32-143` or `gl-030`) where:
 
-## Disable the internal issue tracker
+- `<PROJECT>` starts with a letter and is followed by letters, numbers, or underscores.
+- `<ID>` is a number.
 
-To disable the internal issue tracker in a project:
-
-1. Navigate to the project's **Settings > General** page.
-1. Expand the [permissions section](../settings/index.md#sharing-and-permissions) and switch the **Issues** toggle to disabled.
-
-## Referencing YouTrack issues in GitLab
-
-Issues in YouTrack can be referenced as `<PROJECT>-<ID>`. `<PROJECT>`
-must start with a letter and is followed by letters, numbers, or underscores.
-`<ID>` is a number. An example reference is `YT-101`, `Api_32-143` or `gl-030`.
-
-References to `<PROJECT>-<ID>` in merge requests, commits, or comments are automatically linked to the YouTrack issue URL.
-For more information, see the [External Issue Tracker](../../../integration/external-issue-tracker.md) documentation.
+References to `<PROJECT>-<ID>` in merge requests, commits, or comments are automatically linked
+to the YouTrack issue URL.