Merge branch 'docs/update_epic_docs' into 'master'

Updated Epic docs

See merge request gitlab-org/gitlab!17297

doc/user/group/epics/index.md

@@ -10,13 +10,13 @@ Epics let you manage your portfolio of projects more efficiently and with less
 effort by tracking groups of issues that share a theme, across projects and
 milestones.
 
-![epics list view](img/epics_list_view.png)
+![epics list view](img/epics_list_view_v12.3.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 is targeted to end.
-- Discuss and collaborate on feature ideas and scope at a high-level.
+- Discuss and collaborate on feature ideas and scope at a high level.
 
 ## Creating an epic
 
@@ -24,78 +24,114 @@ A paginated list of epics is available in each group from where you can create
 a new epic. The list of epics includes also epics from all subgroups of the
 selected group. From your group page:
 
-1. Go to **Epics**
-1. Click the **New epic** button at the top right
-1. Enter a descriptive title and hit **Create epic**
+1. Go to **Epics**.
+1. Click **New epic**.
+1. Enter a descriptive title and click **Create epic**.
 
-Once created, you will be taken to the view for that newly-created epic where
-you can change its title, description, start date, and due date.
+You will be taken to the new epic where can edit the following details:
 
-![epic view](img/epic_view.png)
+- Title
+- Description
+- Start date
+- Due date
+- Labels
+
+An epic's page contains the following tabs:
+
+- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are shown in a tree view.
+  - Click on the <kbd>></kbd> beside a parent epic to reveal the child epics and issues.
+- **Roadmap**: a roadmap view of child epics which have start and due dates.
+
+![epic view](img/epic_view_v12.3.png)
 
 ## Adding an issue to an epic
 
+Any issue that belongs to a project in the epic's group, or any of the epic's
+subgroups, are eligible to be added.  New issues appear at the top of the list of issues in the **Epics and Issues** tab.
+
 An epic contains a list of issues and an issue can be associated with at most
-one epic. When on an epic, you can add its associated issues:
+one epic. When you add an issue to an epic that is already associated with another epic,
+the issue is automatically removed from the previous epic.
+
+To add an issue to an epic:
 
-1. Click the plus icon (<kbd>+</kbd>) under the epic description.
-1. Paste the link of the issue (you can hit <kbd>Spacebar</kbd> to add more than
-   one issues at a time).
+1. Click **Add an issue**.
+1. Paste the link of the issue.
+   - Press <kbd>Spacebar</kbd> and repeat this step if there are multiple issues.
 1. Click **Add**.
 
-Any issue belonging to a project in the epic's group or any of the epic's
-subgroups are eligible to be added. To remove an issue from an epic, click
-on the <kbd>x</kbd> button in the epic's issue list.
+To remove an issue from an epic:
 
-NOTE: **Note:**
-When you add an issue or an epic to an epic that's already associated with another epic,
-the issue or the epic is automatically removed from the previous epic.
+1. Click on the <kbd>x</kbd> button in the epic's issue list.
+1. Click **Remove** in the **Remove issue** warning message.
 
 ## Multi-level child epics
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8333) in GitLab Ultimate 11.7.
 
-Much like adding issues to an epic, an epic can have multiple child epics with
-the maximum depth being 5. To add a child epic:
+Any epic that belongs to a group, or subgroup of the parent epic's group, is
+eligible to be added. New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
+
+When you add a child epic that is already associated with another epic,
+that epic is automatically removed from the previous epic.
 
-1. Click the plus icon (<kbd>+</kbd>) under the epic description.
+An epic can have multiple child epics with
+the maximum depth being 5.
+
+To add a child epic:
+
+1. Click **Add an epic**.
 1. Paste the link of the epic.
+   - Press <kbd>Spacebar</kbd> and repeat this step if there are multiple issues.
 1. Click **Add**.
 
-Any epic that belongs to a group or subgroup of the parent epic's group is
-eligible to be added. To remove a child epic from a parent epic,
-click on the <kbd>x</kbd> button in the parent epic's epic list.
+To remove a child epic from a parent epic:
+
+1. Click on the <kbd>x</kbd> button in the parent epic's list of epics.
+1. Click **Remove** in the **Remove epic** warning message.
 
 ## Start date and due date
 
-For each of the dates in the sidebar of an epic, you can choose to either:
+To set a **Start date** and **Due date** for an epic, you can choose either of the following:
 
-- Enter a fixed value.
-- Inherit a dynamic value called "From milestones".
+- **Fixed**: Enter a fixed value.
+- **From milestones:** Inherit a dynamic value from the issues added to the epic.
 
-If you select "From milestones" for the start date, GitLab will automatically set the
+If you select **From milestones** for the start date, GitLab will automatically set the
 date to be earliest start date across all milestones that are currently assigned
-to the issues that are attached to the epic. Similarly, if you select "From milestones"
+to the issues that are added to the epic. Similarly, if you select "From milestones"
 for the due date, GitLab will set it to be the latest due date across all
 milestones that are currently assigned to those issues.
 
-These are dynamic dates in that if milestones are re-assigned to the issues, if the
-milestone dates change, or if issues are added or removed from the epic, then
-the re-calculation will happen immediately to set a new dynamic date.
+These are dynamic dates which are recalculated immediately if any of the following occur:
+
+- Milestones are re-assigned to the issues.
+- Milestone dates change.
+- Issues are added or removed from the epic.
 
-## Roadmap in epics
+## Roadmap
 
 > [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), then you can see a
-[roadmap](../roadmap/index.md) view of the child epics under the parent epic itself.
+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.
 
-![Child epics roadmap](img/child_epics_roadmap.png)
+![Child epics roadmap](img/epic_view_roadmap_v12.3.png)
 
 ## Reordering issues and child epics
 
-Drag and drop to reorder issues and child epics. New issues and child epics added to an epic appear at the top of the list.
+New issues and child epics are added to the top of their respective lists in the **Epics and Issues** tab. You can reorder the list of issues and the list of child epics. Issues and child epics cannot be intermingled.
+
+To reorder issues assigned to an epic:
+
+1. Go to the **Epics and Issues** tab.
+1. Drag and drop issues into the desired order.
+
+To reorder child epics assigned to an epic:
+
+1. Go to the **Epics and Issues** tab.
+1. Drag and drop epics into the desired order.
 
 ## Updating epics
 

doc/user/group/roadmap/index.md

@@ -26,7 +26,7 @@ Epics in the view can be sorted by:
 Each option contains a button that toggles the sort order between **ascending** and **descending**. The sort option and order will be persisted when browsing Epics,
 including the [epics list view](../epics/index.md).
 
-Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics).
+Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap).
 
 ## Timeline duration