Merge branch 'selhorn-docs-epics-1' into 'master'

Edited Epics topic for CTRT

See merge request gitlab-org/gitlab!61303

doc/api/epic_links.md

@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9188) in GitLab 11.8.
 
-Manages parent-child [epic relationships](../user/group/epics/index.md#multi-level-child-epics).
+Manages parent-child [epic relationships](../user/group/epics/manage_epics.md#multi-level-child-epics).
 
 Every API call to `epic_links` must be authenticated.
 

doc/user/group/epics/index.md

@@ -8,57 +8,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Epics **(PREMIUM)**
 
 > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2.
-> - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
+> - Single-level epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
 
-Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md)
-that share a theme across projects and milestones.
+When [issues](../../project/issues/index.md) share a theme across projects and milestones,
+you can manage them by using epics.
 
-An epic's page contains the following tabs:
+You can also create child epics, and assign start and end dates,
+which creates a visual roadmap for you to view progress.
 
-- **Issues**: issues added to this epic.
-- **Epics and Issues**: epics and issues added to this epic.
-  Appears instead of the **Issues** tab if you have access to [multi-level epics](#multi-level-child-epics).
-  Child epics and their issues are shown in a tree view.
+Use epics:
 
-  - To reveal the child epics and issues, select the chevron (**>**) next to a parent epic.
-  - To see a breakdown of open and closed items, hover over the total counts.
-
-    The number provided here includes all epics associated with this project. The number includes
-    epics for which users may not yet have permission.
-
-- [**Roadmap**](#roadmap-in-epics): a roadmap view of child epics which have start and due dates.
-  Appears if you have access to [multi-level epics](#multi-level-child-epics).
-
-![epic view](img/epic_view_v13.0.png)
-
-## Use cases
-
-- Suppose your team is working on a large feature that involves multiple discussions throughout different issues created in distinct projects within a [Group](../index.md). With Epics, you can track all the related activities that together contribute to that single feature.
-- Track when the work for the group of issues is targeted to begin, and when it's targeted to end.
-- Discuss and collaborate on feature ideas and scope at a high level.
-
-## Manage epics
-
-To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include:
-
-- [Create an epic](manage_epics.md#create-an-epic)
-- [Edit an epic](manage_epics.md#edit-an-epic)
-- [Bulk-edit epics](manage_epics.md#bulk-edit-epics)
-- [Delete an epic](manage_epics.md#delete-an-epic)
-- [Close an epic](manage_epics.md#close-an-epic)
-- [Reopen a closed epic](manage_epics.md#reopen-a-closed-epic)
-- [Go to an epic from an issue](manage_epics.md#go-to-an-epic-from-an-issue)
-- [Search for an epic from epics list page](manage_epics.md#search-for-an-epic-from-epics-list-page)
-- [Make an epic confidential](manage_epics.md#make-an-epic-confidential)
-- [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic)
-- [Manage multi-level child epics **(ULTIMATE)**](manage_epics.md#manage-multi-level-child-epics)
+- When your team is working on a large feature that involves multiple discussions
+  in different issues in different projects in a [group](../index.md).
+- To track when the work for the group of issues is targeted to begin and end.
+- To discuss and collaborate on feature ideas and scope at a high level.
 
 ## Relationships between epics and issues
 
 The possible relationships between epics and issues are:
 
 - An epic is the parent of one or more issues.
-- An epic is the parent of one or more child epics. For details see [Multi-level child epics](#multi-level-child-epics). **(ULTIMATE)**
+- An epic is the parent of one or more child epics. For details see [Multi-level child epics](manage_epics.md#multi-level-child-epics).
 
 ```mermaid
 graph TD
@@ -67,72 +37,13 @@ graph TD
     Child_epic --> Issue2
 ```
 
-See [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) for steps
-to:
-
-- Add an issue to an epic
-- Reorder issues
-- Move an issue between epics
-- Promote an issue to an epic
-
-## Issue health status in Epic tree **(ULTIMATE)**
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10.
-> - 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/managing_issues.md#health-status), which then appears on your Epic tree.
-
-## Multi-level child epics **(ULTIMATE)**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7.
-
-You can add any epic that belongs to a group or subgroup of the parent epic's group.
-New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
-
-When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
-
-Epics can contain multiple nested child epics, up to a total of seven levels deep.
-
-See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for
-steps to create, move, reorder, or delete child epics.
-
-## Start date and due date
-
-To set a **Start date** and **Due date** for an epic, select one of the following:
-
-- **Fixed**: enter a fixed value.
-- **Inherited**: inherit a dynamic value from the epic's issues, child epics, and milestones.
-
-### Inherited
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**.
-
-If you select **Inherited**:
-
-- For the **start date**: GitLab scans all child epics and issues assigned to the epic,
-  and sets the start date to match the earliest found start date or milestone.
-- For the **due date**: GitLab sets the due date to match the latest due date or
-  milestone found among its child epics and issues.
-
-These are dynamic dates and recalculated if any of the following occur:
-
-- A child epic's dates change.
-- Milestones are reassigned to an issue.
-- A milestone's dates change.
-- Issues are added to, or removed from, the epic.
-
-Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top.
-If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic.
-The parent epic's start date then reflects this change and propagates upwards to the top epic.
-
 ## Roadmap in epics **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10.
 
-If your epic contains one or more [child epics](#multi-level-child-epics) which
-have a [start or due date](#start-date-and-due-date), a
-[roadmap](../roadmap/index.md) view of the child epics is listed under the parent epic.
+If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that
+have a start or due date, a visual
+[roadmap](../roadmap/index.md) of the child epics is listed under the parent epic.
 
 ![Child epics roadmap](img/epic_view_roadmap_v12_9.png)
 
@@ -144,45 +55,19 @@ epic's issue list.
 If you have access to edit an epic and an issue added to that epic, you can add the issue to or
 remove it from the epic.
 
-Note that for a given group, the visibility of all projects must be the same as
+For a given group, the visibility of all projects must be the same as
 the group, or less restrictive. That means if you have access to a group's epic,
 then you already have access to its projects' issues.
 
 You can also consult the [group permissions table](../../permissions.md#group-members-permissions).
 
-## Thread
-
-- Comments: collaborate on that epic by posting comments in its thread.
-  These text fields also fully support
-  [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown).
-
-## Comment or start a thread
-
-Once you write your comment, you can either:
-
-- Click **Comment** to publish your comment.
-- Click **Start thread** to start a thread within that epic's discussion.
-
-### Activity sort order
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
-
-You can reverse the default order and interact with the activity feed sorted by most recent items
-at the top. Your preference is saved via local storage and automatically applied to every issue
-you view.
-
-To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest
-or newest items to be shown first.
-
-![Issue activity sort order dropdown button](img/epic_activity_sort_order_v13_2.png)
-
-## Award emoji
-
-You can [award an emoji](../../award_emojis.md) to that epic or its comments.
-
-## Notifications
+## Related topics
 
-You can [turn on notifications](../../profile/notifications.md) to be alerted about epic events.
+- [Manage epics](manage_epics.md) and multi-level child epics.
+- [Turn on notifications](../../profile/notifications.md) for about epic events.
+- [Award an emoji](../../award_emojis.md) to an epic or its comments.
+- Collaborate on an epic by posting comments in a [thread](../../discussions/index.md).
+- Use [health status](../../project/issues/managing_issues.md#health-status) to track your progress.
 
 <!-- ## Troubleshooting
 

doc/user/group/epics/manage_epics.md

@@ -16,28 +16,46 @@ to them.
 
 > - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
 > - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form.
-> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty Roadmap.
+> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty roadmap.
 
 To create an epic in the group you're in:
 
 1. Get to the New Epic form:
-   - From the **Epics** list in your group, select **New epic**.
+   - Go to your group and from the left sidebar select **Epics**. Then select **New epic**.
    - From an epic in your group, select **New epic**.
    - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**.
    - In an empty [roadmap](../roadmap/index.md), select **New epic**.
 
-     ![New epic from an open epic](img/new_epic_from_groups_v13.7.png)
+1. Enter a title.
+1. Optional. Enter a description.
+1. Optional. To make the epic confidential, select the [Confidentiality checkbox](#make-an-epic-confidential).
+1. Optional. Choose labels.
+1. Optional. Select a start and due date, or [inherit](#start-and-due-date-inheritance) them.
+1. Select **Create epic**.
 
-1. Fill in these fields:
+The newly created epic opens.
 
-   - Title
-   - Description
-   - [Confidentiality checkbox](#make-an-epic-confidential)
-   - Labels
-   - Start date
-   - Due date
+### Start and due date inheritance
 
-1. Select **Create epic**. You are taken to view the newly created epic.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**.
+
+If you select **Inherited**:
+
+- For the **start date**: GitLab scans all child epics and issues assigned to the epic,
+  and sets the start date to match the earliest found start date or milestone.
+- For the **due date**: GitLab sets the due date to match the latest due date or
+  milestone found among its child epics and issues.
+
+These are dynamic dates and recalculated if any of the following occur:
+
+- A child epic's dates change.
+- Milestones are reassigned to an issue.
+- A milestone's dates change.
+- Issues are added to, or removed from, the epic.
+
+Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top.
+If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic.
+The parent epic's start date then reflects this change and propagates upwards to the top epic.
 
 ## Edit an epic
 
@@ -55,7 +73,7 @@ To edit an epic's title or description:
 1. Make your changes.
 1. Select **Save changes**.
 
-To edit an epics' start date, due date, or labels:
+To edit an epic's start date, due date, or labels:
 
 1. Select **Edit** next to each section in the epic sidebar.
 1. Select the dates or labels for your epic.
@@ -151,6 +169,19 @@ The sort option and order is saved and used wherever you browse epics, including
 
 ![epics sort](img/epics_sort.png)
 
+## Change activity sort order
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
+
+You can reverse the default order and interact with the activity feed sorted by most recent items
+at the top. Your preference is saved via local storage and automatically applied to every epic and issue
+you view.
+
+To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest
+or newest items to be shown first.
+
+![Issue activity sort order dropdown button](img/epic_activity_sort_order_v13_2.png)
+
 ## Make an epic confidential
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0 behind a feature flag, disabled by default.
@@ -200,6 +231,13 @@ To add a new issue to an epic:
    If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step.
 1. Select **Add**.
 
+#### View count of issues in an epic
+
+On the **Epics and Issues** tab, under each epic name, hover over the total counts.
+
+The number indicates all epics associated with the project, including issues
+you might not have permission to.
+
 #### Create an issue from an epic
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5419) in GitLab 12.7.
@@ -286,9 +324,16 @@ For an introduction to epic templates, see [GitLab Epics and Epic Template Tip](
 
 For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/).
 
-## Manage multi-level child epics **(ULTIMATE)**
+## Multi-level child epics **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7.
+
+You can add any epic that belongs to a group or subgroup of the parent epic's group.
+New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
+
+When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
 
-With [multi-level epics](index.md#multi-level-child-epics), you can manage more complex projects.
+Epics can contain multiple nested child epics, up to a total of seven levels deep.
 
 ### Add a child epic to an epic
 

doc/user/project/issues/managing_issues.md

@@ -62,7 +62,7 @@ When you're creating a new issue, these are the fields you can fill in:
 - Checkbox to make the issue confidential
 - Assignee
 - Weight
-- Epic **(PREMIUM)**
+- [Epic](../../group/epics/index.md)
 - Due date
 - Milestone
 - Labels
@@ -402,5 +402,4 @@ This marks issues as progressing as planned or needs attention to keep on schedu
 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).
+You can then see issue statuses in the issues list and the epic tree.