Change location of epics docs and refactor

doc/README.md

@@ -62,6 +62,7 @@ Shortcuts to GitLab's most visited docs:
   - [GitLab Pages](user/project/pages/index.md): Build, test, and deploy your static website with GitLab Pages.
 - [Groups](user/group/index.md): Organize your projects in groups.
   - [Subgroups](user/group/subgroups/index.md)
+  - [Epics](user/group/epics/index.md)
 - [Search through GitLab](user/search/index.md): Search for issues, merge requests, projects, groups, todos, and issues in Issue Boards.
   - **(EES/EEP)** [Advanced Global Search](user/search/advanced_global_search.md): Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance.
   - **(EES/EEP)** [Advanced Syntax Search](user/search/advanced_search_syntax.md): Use advanced queries for more targeted search results.

doc/user/group/epics/index.md

+# Epics
+
+> Introduced in [GitLab Enterprise Edition Ultimate][ee] 10.2.
+
+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.
+
+## Creating an epic
+
+A paginated list of epics is available in each group from where you can create
+a new epic. 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**
+
+Once created, you will be taken to the view for that newly-created epic where
+you can change its title, description, planned start date, and planned end date.
+The planned end date cannot be before the planned start date
+(but they can be the same day).
+
+![epic view](img/epic_view.png)
+
+An epic contains a list of issues, and an issue can be associated with at most
+one epic. You can add issues associated with the epic by clicking the
+plus icon (<kbd>+</kbd>) under the epic description, pasting the link of the
+issue, and clicking **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, simply click on the <kbd>x</kbd> button in the epic's
+issue list.
+
+When you add an issue to an epic that's already associated with another epic,
+the issue is automatically removed from the previous epic. In other words, an
+issue can be associated with at most one epic.
+
+## Deleting an epic
+
+Deleting an epic releases all existing issues from their associated epic in the
+system.
+
+## Permissions
+
+If you have access to view an epic and have access to view an issue already
+added to that epic, then you can view the issue in the epic issue list.
+
+If you have access to edit an epic and have access to edit an issue, then 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
+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 may also consult the
+[group permissions table](../../permissions.md#group-members-permissions).
+
+[ee]: https://about.gitlab.com/gitlab-ee/

doc/user/group/index.md

@@ -61,41 +61,6 @@ Issues and merge requests are part of projects. For a given group, view all the
 [issues](../project/issues/index.md#issues-per-group) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all the projects in that group,
 together in a single list view.
 
-## Epics
-
-> Introduced in [GitLab Enterprise Edition Ultimate][ee] 10.2.
-
-With epics you can plan and track your work at the feature level by collecting
-multiple related issues together in the same group/subgroup.
-
-A paginated list of epics is available in each group from where you can create
-a new epic. From the group page, click the **New epic** button at the top right,
-enter a descriptive title and hit **Create epic**.
-
-Once created, you will be taken to the view for that newly-created epic where
-you can change its title, description, planned start date, and planned end date.
-The planned end date cannot be before the planned start date
-(but they can be the same day).
-
-![epic view](img/epic-view.png)
-
-An epic contains a list of issues and an issue can be associated with at most
-one epic. You can add issues associated with the epic by clicking the
-plus icon (<kbd>+</kbd>) under the epic description, pasting the link of the
-issue, and clicking **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, simply click on the <kbd>x</kbd> button in the epic's
-issue list.
-
-When you add an issue to an epic that's already associated with another epic,
-the issue is automatically removed from the previous epic. In other words, an
-issue can be associated with at most one epic.
-
-Deleting an epic releases all existing issues from their associated epic in the
-system.
-
-[See group permissions for epics and associating issues.](../permissions.md#group-members-permissions)
-
 ## Create a new group
 
 > **Notes:**
@@ -210,6 +175,16 @@ Alternatively, you can [lock the sharing with group feature](#share-with-group-l
 In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups.
 See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information.
 
+## Epics
+
+> Introduced in [GitLab Enterprise Edition Ultimate][ee] 10.2.
+
+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.
+
+[Learn more about Epics.](epics/index.md)
+
 ## Group settings
 
 Once you have created a group, you can manage its settings by navigating to

doc/user/permissions.md

@@ -152,16 +152,6 @@ group.
 | View public group epic   | ✓       | ✓        | ✓         | ✓      | ✓     |
 | Create/edit group epic   |         | ✓        | ✓         | ✓      | ✓     |
 
-If you have access to view an epic and have access to view an issue already added to that epic,
-then you can view the issue in the epic issue list.
-
-If you have access to edit an epic and have access to edit an issue, then 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 the
-group, or less restrictive. So that means if you have access to a group's epic, then 
-you already have access to its projects' issues.
-
 ### Subgroup permissions
 
 When you add a member to a subgroup, they inherit the membership and