Merge branch 'selhorn-issues-edits' into 'master'

Edited for style and CTRT

See merge request gitlab-org/gitlab!57169

doc/administration/instance_limits.md

@@ -149,7 +149,7 @@ limited to 1KiB, and descriptions (the rest of the message) will be limited to
 
 The maximum number of issues loaded on the milestone overview page is 3000.
 When the number exceeds the limit the page displays an alert and links to a paginated
-[issue list](../user/project/issues/index.md#issues-list) of all issues in the milestone.
+[issue list](../user/project/issues/managing_issues.md) of all issues in the milestone.
 
 - **Limit:** 3000 issues
 

doc/user/group/bulk_editing/index.md

@@ -31,7 +31,7 @@ When bulk editing issues in a group, you can edit the following attributes:
 - [Epic](../epics/index.md)
 - [Milestone](../../project/milestones/index.md)
 - [Labels](../../project/labels.md)
-- [Health status](../../project/issues/index.md#health-status)
+- [Health status](../../project/issues/managing_issues.md#health-status)
 - [Iteration](../iterations/index.md)
 
 To update multiple project issues at the same time:

doc/user/group/epics/index.md

@@ -81,7 +81,7 @@ to:
 > - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7.
 
-Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/index.md#health-status), which then appears on your Epic tree.
+Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/managing_issues.md#health-status), which then appears on your Epic tree.
 
 ## Multi-level child epics **(ULTIMATE)**
 

doc/user/group/index.md

@@ -16,7 +16,7 @@ Then you can:
 
 - Grant members access to multiple projects at once.
 - Add to-do items for all of the group members at once.
-- View the [issues](../project/issues/index.md#issues-list) and
+- View the [issues](../project/issues/index.md) and
   [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group)
   for all projects in the group, together in a single list view.
 - [Bulk edit](../group/bulk_editing/index.md) issues, epics, and merge requests.

doc/user/index.md

@@ -42,7 +42,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools
 
 - Hosting code in repositories with version control.
 - Tracking proposals for new implementations, bug reports, and feedback with a
-  fully featured [Issue Tracker](project/issues/index.md#issues-list).
+  fully featured [Issue tracker](project/issues/index.md).
 - Organizing and prioritizing with [Issue Boards](project/issue_board.md).
 - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per
   branch with [Review Apps](../ci/review_apps/index.md).

doc/user/project/bulk_editing.md

@@ -33,7 +33,7 @@ When bulk editing issues in a project, you can edit the following attributes:
 - [Epic](../group/epics/index.md)
 - [Milestone](milestones/index.md)
 - [Labels](labels.md)
-- [Health status](issues/index.md#health-status)
+- [Health status](issues/managing_issues.md#health-status)
 - Notification subscription
 - [Iteration](../group/iterations/index.md)
 

doc/user/project/issue_board.md

@@ -14,7 +14,7 @@ It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development))
 It pairs issue tracking and project management, keeping everything together,
 so that you don't need to jump between different platforms to organize your workflow.
 
-Issue boards build on the existing [issue tracking functionality](issues/index.md#issues-list) and
+Issue boards build on the existing [issue tracking functionality](issues/index.md) and
 [labels](labels.md). Your issues appear as cards in vertical lists, organized by their assigned
 labels, [milestones](#milestone-lists), or [assignees](#assignee-lists).
 
@@ -88,7 +88,7 @@ You can tailor GitLab issue boards to your own preferred workflow.
 Here are some common use cases for issue boards.
 
 For examples of using issue boards along with [epics](../group/epics/index.md),
-[issue health status](issues/index.md#health-status), and
+[issue health status](issues/managing_issues.md#health-status), and
 [scoped labels](labels.md#scoped-labels) for various Agile frameworks, check:
 
 - The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020)

doc/user/project/issues/due_dates.md

@@ -37,7 +37,7 @@ The last way to set a due date is by using [quick actions](../quick_actions.md),
 
 ## Making use of due dates
 
-You can see issues with their due dates in the [issues list](index.md#issues-list).
+You can see issues with their due dates in the issues list.
 Overdue issues have their icon and date colored red.
 To sort issues by their due dates, select **Due date** from the dropdown menu on the right.
 Issues are then sorted from the earliest due date to the latest.

doc/user/project/issues/index.md

@@ -6,209 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Issues **(FREE)**
 
-Issues are the fundamental mechanism in GitLab to collaborate on ideas, solve
-problems, and plan work.
-
-Using issues, you can share and discuss proposals (both before and during their
-implementation) between you and your team, and outside collaborators.
+Use issues to collaborate on ideas, solve problems, and plan work.
+Share and discuss proposals with your team and with outside collaborators.
 
 You can use issues for many purposes, customized to your needs and workflow.
-Common use cases include:
 
-- Discussing the implementation of a new idea.
-- Tracking tasks and work status.
-- Accepting feature proposals, questions, support requests, or bug reports.
-- Elaborating on new code implementations.
+- Discuss the implementation of an idea.
+- Track tasks and work status.
+- Accept feature proposals, questions, support requests, or bug reports.
+- Elaborate on code implementations.
 
-For more information about using issues, see the
-[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/)
-GitLab blog post.
+For more information about using issues, see the GitLab blog post:
+[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/).
 
 Issues are always associated with a specific project. If you have multiple
-projects in a group, you can view all of the issues collectively at the group
-level.
+projects in a group, you can view all of the projects' issues at once.
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and
+To learn how the GitLab Strategic Marketing department uses GitLab issues with [labels](../labels.md) and
 [issue boards](../issue_board.md), see the video on
 [Managing Commitments with Issues](https://www.youtube.com/watch?v=cuIHNintg1o&t=3).
 
-## Parts of an issue
-
-Issues have a flexible content and metadata structure. Here are some of the
-elements you can provide in an issue:
-
-- Title
-- Description and tasks
-- Comments and other activity
-- Author
-- Assignees
-- State (open or closed)
-- Health status (on track, needs attention, or at risk)
-- Confidentiality
-- Tasks (completed vs. outstanding)
-- Milestone
-- Due date
-- Weight
-- Time tracking
-- Labels
-- Votes
-- Reaction emoji
-- Linked issues
-- Assigned epic
-- Unique issue number and URL
-
-## View and manage issues
-
-Key actions for issues include:
-
-- [Creating issues](managing_issues.md#create-a-new-issue)
-- [Moving issues](managing_issues.md#moving-issues)
-- [Closing issues](managing_issues.md#closing-issues)
-- [Deleting issues](managing_issues.md#deleting-issues)
-- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic)
-
-Although you can view and manage details of an issue on the [issue page](#issue-page),
-you can also work with several issues at a time by using these features:
-
-- [Issues List](#issues-list): View a list of issues in a project or group.
-- [Issue Boards](../issue_board.md): Organize issues with a project management
-  workflow for a feature or product release.
-- Issue references
-- [Epics](../../group/epics/index.md): Manage your portfolio of projects by
-  tracking groups of issues with a shared theme.
-
-### Issue page
-
-![Issue view](img/issues_main_view.png)
-
-On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md),
-and modify them if you have the necessary [permissions](../../permissions.md).
-
-#### Real-time sidebar **(FREE SELF)**
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3.
-
-Assignees in the sidebar are updated in real time. This feature is **disabled by default**.
-To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html).
-
-### Issues List
-
-![Project Issues List view](img/project_issues_list_view.png)
-
-In the Issues List, you can:
-
-- View all issues in a project when opening the Issues List from a project context.
-- View all issues in a groups's projects when opening the Issues List from a group context.
-
-You can filter the Issues List with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists),
-including specific metadata, such as labels, assignees, status, and more. From this
-view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues.
-
-For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page
-for a rundown of all the fields and information in an issue.
-
-You can sort a list of issues in several ways, for example by issue creation date, milestone due date.
-For more information, see the [Sorting and ordering issue lists](sorting_issue_lists.md) page.
-
-#### Cached issue count
-
-> - [Introduced]([link-to-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/243753)) in GitLab 13.9.
-> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default.
-> - It's disabled on GitLab.com.
-> - It's not recommended for production use.
-> - To use this feature in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cached-issue-count) **(FREE SELF)**
-
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
-
-In a group, the sidebar displays the total count of open issues and this value is cached if higher
-than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours.
-
-### Design Management
-
-With [Design Management](design_management.md), you can upload design
-assets to issues and view them all together for sharing and
-collaboration with your team.
-
-### Related issues
-
-You can mark two issues as related, so that when viewing one, the other is always
-listed in its [Related Issues](related_issues.md) section. This can help display important
-context, such as past work, dependencies, or duplicates.
-
-Users of [GitLab Premium](https://about.gitlab.com/pricing/) or higher can
-also mark issues as blocking or blocked by another issue.
-
-### Crosslinking issues
-
-You can [cross-link issues](crosslinking_issues.md) by referencing an issue from another
-issue or merge request by including its URL or ID. The referenced issue displays a
-message in the Activity stream about the reference, with a link to the other issue or MR.
-
-### Similar issues
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22866) in GitLab 11.6.
-
-To prevent duplication of issues for the same topic, GitLab searches for similar issues
-when new issues are being created.
-
-As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions
-across all issues to in the current project. Only issues you have access to are returned.
-Up to five similar issues, sorted by most recently updated, are displayed below the title box.
-[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature.
-
-![Similar issues](img/similar_issues.png)
-
-### Health status **(ULTIMATE)**
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10.
-> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later.
-> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7.
-
-To help you track issue statuses, you can assign a status to each issue.
-This marks issues as progressing as planned or needs attention to keep on schedule:
-
-- **On track** (green)
-- **Needs attention** (amber)
-- **At risk** (red)
-
-!["On track" health status on an issue](img/issue_health_status_dropdown_v12_10.png)
-
-After an issue is closed, its health status can't be edited and the "Edit" button becomes disabled
-until the issue is reopened.
-
-You can then see issue statuses in the [issue list](#issues-list) and the
-[Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree).
-
-## Other Issue actions
+## Related topics
 
+- [Create issues](managing_issues.md#create-a-new-issue)
 - [Create an issue from a template](../../project/description_templates.md#use-the-templates)
+- [Move issues](managing_issues.md#moving-issues)
+- [Close issues](managing_issues.md#closing-issues)
+- [Delete issues](managing_issues.md#deleting-issues)
+- [Promote issues](managing_issues.md#promote-an-issue-to-an-epic)
 - [Set a due date](due_dates.md)
-- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues
-  in order to change their status, assignee, milestone, or labels in bulk.
 - [Import issues](csv_import.md)
 - [Export issues](csv_export.md)
+- [Upload designs to issues](design_management.md)
+- [Relate issues](related_issues.md)
+- [Cross-link issues](crosslinking_issues.md)
+- [Bulk edit issues](../bulk_editing.md)
+- [Sort issue lists](sorting_issue_lists.md) 
+- [Search for issues](../../search/index.md#filtering-issue-and-merge-request-lists)
+- [Epics](../../group/epics/index.md)
+- [Issue Boards](../issue_board.md)
 - [Issues API](../../../api/issues.md)
-- Configure an [external issue tracker](../../../integration/external-issue-tracker.md)
-  such as Jira, Redmine, Bugzilla, or EWM.
-
-## Enable or disable cached issue count **(FREE SELF)**
-
-Cached issue count in the left sidebar is under development and not ready for production use. It is
-deployed behind a feature flag that is **enabled by default**.
-[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
-can disable it.
-
-To disable it:
-
-```ruby
-Feature.disable(:cached_sidebar_open_issues_count)
-```
-
-To enable it:
-
-```ruby
-Feature.enable(:cached_sidebar_open_issues_count)
-```
+- [Configure an external issue tracker](../../../integration/external-issue-tracker.md)
+- [Parts of an issue](issue_data_and_actions.md)

doc/user/project/issues/managing_issues.md

@@ -144,7 +144,7 @@ Follow these examples to form your new issue URL with prefilled fields.
 - For a new issue in the GitLab Community Edition project with a pre-filled title,
   a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true`
 
-## Moving Issues
+## Moving issues
 
 Moving an issue copies it to the target project, and closes it in the originating project.
 The original issue is not deleted. A system note, which indicates
@@ -154,7 +154,7 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i
 
 ![move issue - button](img/sidebar_move_issue.png)
 
-### Moving Issues in Bulk
+### Moving issues in bulk **(FREE SELF)**
 
 If you have advanced technical skills you can also bulk move all the issues from
 one project to another in the rails console. The below script moves all issues
@@ -315,3 +315,79 @@ To add an issue to an [iteration](../../group/iterations/index.md):
 You can also use the `/iteration`
 [quick action](../quick_actions.md#issues-merge-requests-and-epics)
 in a comment or description field.
+
+## Real-time sidebar **(FREE SELF)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3.
+
+Assignees in the sidebar are updated in real time. This feature is **disabled by default**.
+To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html).
+
+## Cached issue count **(FREE SELF)**
+
+> - [Introduced]([link-to-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/243753)) in GitLab 13.9.
+> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default.
+> - It's disabled on GitLab.com.
+> - It's not recommended for production use.
+> - To use this feature in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cached-issue-count) **(FREE SELF)**
+
+WARNING:
+This feature might not be available to you. Check the **version history** note above for details.
+
+In a group, the sidebar displays the total count of open issues and this value is cached if higher
+than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours.
+
+## Similar issues
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22866) in GitLab 11.6.
+
+To prevent duplication of issues for the same topic, GitLab searches for similar issues
+when new issues are being created.
+
+As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions
+across all issues to in the current project. Only issues you have access to are returned.
+Up to five similar issues, sorted by most recently updated, are displayed below the title box.
+[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature.
+
+![Similar issues](img/similar_issues.png)
+
+## Health status **(ULTIMATE)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10.
+> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later.
+> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7.
+
+To help you track issue statuses, you can assign a status to each issue.
+This marks issues as progressing as planned or needs attention to keep on schedule:
+
+- **On track** (green)
+- **Needs attention** (amber)
+- On track (green)
+- Needs attention (amber)
+- At risk (red)
+
+After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled
+until the issue is reopened.
+
+You can then see issue statuses in the issues list and the
+[epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree).
+
+## Enable or disable cached issue count **(FREE SELF)**
+
+Cached issue count in the left sidebar is under development and not ready for production use. It is
+deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can disable it.
+
+To disable it:
+
+```ruby
+Feature.disable(:cached_sidebar_open_issues_count)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:cached_sidebar_open_issues_count)
+```