Merge branch 'docs/copyedit-epics' into 'master'

Copyedit Epics docs

Closes #4062

See merge request gitlab-org/gitlab-ee!3482

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)
+  - **(EEU)** [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
+
+NOTE: **Note:**
+To delete an epic, you need to be an [Owner][permissions] of a group/subgroup.
+
+When inside a single epic view, click the **Delete** button to delete the epic.
+A modal will pop-up to confirm your action.
+
+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].
+
+[ee]: https://about.gitlab.com/gitlab-ee/
+[permissions]: ../../permissions.md#group-members-permissions

doc/user/group/index.md

@@ -61,39 +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
-
-Epics are available in GitLab Enterprise Edition Ultimate. Epics are designed to 
-enable you plan and track work at the feature level, as opposed to the design and 
-implementation details level of an issue.
-
-Epics are scoped at the group level. A paginated list of epics is available in each
-group. From this page, you can also click the `New epic` button at the top right to
-create a new epic. Creating a new epic will bring you to the epic view itself for
-that newly created epic.
-
-![epics list view](img/epics-list-view.png)
-
-When creating an epic, you only specify its title.
-For existing epics, you can add/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).
-
-An epic contains a list of issues. And an issue can be associated with at most one epic.
-In an epic, you add (and remove) issues associated with the epic by clicking `+`,
-pasting in the link to the issue, and clicking `Add`. Any issue belonging to a project 
-in the epic's group or any of the epic's subgroups can are eligible to be added. 
-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.
-
-You can also delete an epic from the epic view. Deleting an epic releases all existing
-issues fromt their associated epic in the system.
-
-![epic view](img/epic-view.png)
-
-[See group permissions for epics and associating issues.](../permissions.md#group-members-permissions)
-
 ## Create a new group
 
 > **Notes:**
@@ -208,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

@@ -151,16 +151,7 @@ group.
 | View internal group epic | ✓       | ✓        | ✓         | ✓      | ✓     |
 | 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.
+| Delete group epic        |         |          |           |        | ✓     |
 
 ### Subgroup permissions