Merge branch 'gweaver-master-patch-2c01' into 'master'

Improves the technical accuracy of two Plan related documentation pages

Closes gitlab-com/gitlab-OKRs#8490

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170611



Merged-by: Marcin Sedlak-Jakubowski <msedlakjakubowski@gitlab.com>
Co-authored-by: Gabe Weaver <gweaver@gitlab.com>

doc/user/project/issues/managing_issues.md

@@ -43,8 +43,11 @@ Generate a detailed description for an issue based on a short summary you provid
 Prerequisites:
 
 - You must belong to at least one group with the [experiment and beta features setting](../../gitlab_duo/turn_on_off.md#turn-on-beta-and-experimental-features) enabled.
-- You must have permission to view the issue.
+- You must have permission to create an issue.
 - Only available for the plain text editor.
+- Only available when creating a new issue.
+  For a proposal to add support for generating descriptions when editing existing issues, see
+  [issue 474141](https://gitlab.com/gitlab-org/gitlab/-/issues/474141).
 
 To generate an issue description:
 
@@ -59,22 +62,6 @@ Provide feedback on this experimental feature in [issue 409844](https://gitlab.c
 **Data usage**: When you use this feature, the text you enter is sent to
 the [large language model listed on the GitLab Duo page](../../gitlab_duo/index.md#issue-description-generation).
 
-### Remove a task list item
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9.
-
-Prerequisites:
-
-- You must have at least the Reporter role for the project, or be the author or assignee of the issue.
-
-In an issue description with task list items:
-
-1. Hover over a task list item and select the options menu (**{ellipsis_v}**).
-1. Select **Delete**.
-
-The task list item is removed from the issue description.
-Any nested task list items are moved up a nested level.
-
 ## Bulk edit issues from a project
 
 You can edit multiple issues at a time when you're in a project.
@@ -153,14 +140,16 @@ To move an issue:
 1. Search for a project to move the issue to.
 1. Select **Move**.
 
+You can also use the `/move` [quick action](../quick_actions.md) in a comment or description.
+
 ### Moving tasks when the parent issue is moved
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `move_issue_children`. Disabled by default.
 > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 16.11.
 > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 17.3. Feature flag `move_issue_children` removed.
 
-When you move an issue to another project, all its child tasks are also
-moved to the target project and remain associated as child tasks on the moved issue.
+When you move an issue to another project, all its child tasks are also moved to the target project
+and remain as child tasks of the moved issue.
 Each task is moved the same way as the parent, that is, it's closed in the original project and
 copied to the target project.
 
@@ -224,7 +213,31 @@ To do it:
 
 1. To exit the Rails console, enter `quit`.
 
-## Reorder list items in the issue description
+## Description lists and task lists
+
+When you use ordered lists, unordered lists, or task lists in issue descriptions, you can:
+
+- Reorder list items with drag and drop
+- Delete list items
+- [Convert task list items to GitLab Tasks](../../tasks.md#from-a-task-list-item)
+
+### Delete a task list item
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9.
+
+Prerequisites:
+
+- You must have at least the Reporter role for the project, or be the author or assignee of the issue.
+
+In an issue description with task list items:
+
+1. Hover over a task list item and select the options menu (**{ellipsis_v}**).
+1. Select **Delete**.
+
+The task list item is removed from the issue description.
+Any nested task list items are moved up a nested level.
+
+### Reorder list items in the issue description
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.0.
 
@@ -261,6 +274,8 @@ To close an issue, you can either:
   1. Select **Plan > Issues**, then select your issue to view it.
   1. In the upper-right corner, select **Issue actions** (**{ellipsis_v}**) and then **Close issue**.
 
+You can also use the `/close` [quick action](../quick_actions.md) in a comment or description.
+
 ### Reopen a closed issue
 
 Prerequisites:
@@ -270,6 +285,8 @@ Prerequisites:
 To reopen a closed issue, in the upper-right corner, select **Issue actions** (**{ellipsis_v}**) and then **Reopen issue**.
 A reopened issue is no different from any other open issue.
 
+You can also use the `/reopen` [quick action](../quick_actions.md) in a comment or description.
+
 ### Closing issues automatically
 
 You can close issues automatically by using certain words, called a _closing pattern_,
@@ -438,13 +455,12 @@ DETAILS:
 
 You can promote an issue to an [epic](../../group/epics/index.md) in the immediate parent group.
 
-NOTE:
-Promoting a confidential issue to an epic makes all information
-related to the issue public, as epics are public to group members.
+Promoting a confidential issue to an epic creates a
+[confidential epic](../../group/epics/manage_epics.md#make-an-epic-confidential), retaining
+confidentiality.
 
 When an issue is promoted to an epic:
 
-- If the issue was confidential, an additional warning is displayed first.
 - An epic is created in the same group as the project of the issue.
 - Subscribers of the issue are notified that the epic was created.
 
@@ -494,7 +510,11 @@ To add an issue to an [iteration](../../group/iterations/index.md):
 1. From the dropdown list, select the iteration to add this issue to.
 1. Select any area outside the dropdown list.
 
-Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics).
+To add an issue to an iteration, you can also:
+
+- Use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics)
+- Drag an issue into an iteration list in a board
+- Bulk edit issues from the issues list
 
 ## View all issues assigned to you
 
@@ -557,8 +577,7 @@ To filter the list issues for text in a title or description:
 1. On the left sidebar, select **Search or go to** and find your project.
 1. Select **Plan > Issues**.
 1. Above the list of issues, in the **Search or filter results** text box, enter the searched phrase.
-1. In the dropdown list that appears, select **Search for this text**.
-1. Select the text box again, and in the dropdown list that appears, select **Search Within**, and then either **Titles** or **Descriptions**.
+1. In the dropdown list that appears, select **Search within**, and then either **Titles** or **Descriptions**.
 1. Press <kbd>Enter</kbd> or select the search icon (**{search}**).
 
 Filtering issues uses [PostgreSQL full text search](https://www.postgresql.org/docs/current/textsearch-intro.html)
@@ -567,7 +586,7 @@ to match meaningful and significant words to answer a query.
 For example, if you search for `I am securing information for M&A`,
 GitLab can return results with `securing`, `secured`,
 or `information` in the title or description.
-However, GitLab won't match the sentence or the words `I`, `am` or `M&A` exactly,
+However, GitLab doesn't match the sentence or the words `I`, `am` or `M&A` exactly,
 as they aren't deemed lexically meaningful or significant.
 It's a limitation of PostgreSQL full text search.
 
@@ -591,7 +610,7 @@ You can use the OR operator (**is one of: `||`**) when you [filter the list of i
 
 1. On the left sidebar, select **Search or go to** and find your project.
 1. Select **Plan > Issues**.
-1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10.
+1. In the **Search** box, type `#` followed by the issue ID. For example, enter filter `#10` to return only issue 10.
 
 ![filter issues by specific ID](img/issue_search_by_id_v15_0.png)
 

doc/user/project/milestones/index.md

@@ -10,7 +10,10 @@ DETAILS:
 **Tier:** Free, Premium, Ultimate
 **Offering:** GitLab.com, Self-managed, GitLab Dedicated
 
-Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time.
+Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal
+in a certain period of time, such as a program increment or upcoming release.
+When you use milestones together with [iterations](../../group/iterations/index.md), you can track
+work across two concurrent timeboxes with different start and end dates.
 
 Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date.
 
@@ -18,11 +21,14 @@ Milestones allow you to organize issues and merge requests into a cohesive group
 
 Milestones can be used to track releases. To do so:
 
-1. Set the milestone due date to represent the release date of your release and leave the milestone start date blank.
+1. Set the milestone due date to represent the release date of your release.
+   If you do not have a defined start date for your release cycle, you can leave the milestone start
+   date blank.
 1. Set the milestone title to the version of your release, such as `Version 9.4`.
-1. Add an issue to your release by associating the desired milestone from the issue's right-hand sidebar.
+1. Add issues to your release by selecting the milestone from the issue's right sidebar.
 
-Additionally, you can integrate milestones with the [Releases feature](../releases/index.md#associate-milestones-with-a-release).
+Additionally, to automatically generate release evidence when you create your release, integrate
+milestones with the [Releases feature](../releases/index.md#associate-milestones-with-a-release).
 
 ## Project milestones and group milestones
 
@@ -44,7 +50,7 @@ To view the milestone list:
 1. Select **Plan > Milestones**.
 
 In a project, GitLab displays milestones that belong to the project.
-In a group, GitLab displays milestones that belong to the group and all projects in the group.
+In a group, GitLab displays milestones that belong to the group and all projects and subgroups in the group.
 
 ### View milestones in a project with issues turned off
 
@@ -98,16 +104,19 @@ The tabs below the title and description show the following:
 The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md),
 showing the progress of completing a milestone.
 
-![burndown chart](img/burndown_and_burnup_charts_v15_3.png)
+![burndown and burnup chart](img/burndown_and_burnup_charts_v15_3.png)
 
 #### Milestone sidebar
 
-The milestone sidebar on the milestone view shows the following:
+The sidebar on the milestone view shows the following:
 
 - Percentage complete, which is calculated as number of closed issues divided by total number of issues.
 - The start date and due date.
 - The total time spent on all issues and merge requests assigned to the milestone.
 - The total issue weight of all issues assigned to the milestone.
+- The count of total, open, closed, and merged merge requests.
+- Links to associated releases.
+- The milestone's reference you can copy to your clipboard.
 
 ![Project milestone page](img/milestones_project_milestone_page_sidebar_v13_11.png)
 
@@ -185,7 +194,8 @@ To delete a milestone:
 ## Promote a project milestone to a group milestone
 
 If you are expanding the number of projects in a group, you might want to share the same milestones
-among this group's projects. You can also promote project milestones to group milestones to
+among this group's projects.
+You can promote project milestones to the parent group to
 make them available to other projects in the same group.
 
 Promoting a milestone merges all project milestones across all projects in this group with the same
@@ -223,7 +233,11 @@ To assign or unassign a milestone:
    You can select from both project and group milestones.
 1. Select the milestone you want to assign.
 
-You can also use the `/assign` [quick action](../quick_actions.md) in a comment.
+To assign or unassign a milestone, you can also:
+
+- Use the `/milestone` [quick action](../quick_actions.md) in a comment or description
+- Drag an issue to a [milestone list](../issue_board.md#milestone-lists) in a board
+- [Bulk edit issues](../issues/managing_issues.md#bulk-edit-issues-from-a-project) from the issues list
 
 ## Filter issues and merge requests by milestone