Review and reorganize Epics docs

Problem to solve

The Epics documentation page is difficult to use:

• It mixes content types in a non-obvious order
• Headings formatted as gerunds are difficult to scan

Further details

Proposal

• Change "-ing" headings to infinitive forms.
• • Separate sections in "buckets", for example:
    • Instructive sections to "Manage GitLab Epics"
    • Sections on Epic UI elements to something like "Parts of an epic".
• Remove unneeded screenshots and some where they're most needed.
• Provide more on the WHY in the main page and the "Use cases" section.

Page reorganization

Current structure

https://docs.gitlab.com/ee/user/group/epics/index.html

• Relationships between epics and issues
• Use cases
• Creating an epic
• Adding an issue to an epic
  • Adding an existing issue to an epic
  • Creating an issue from an epic
• Issue health status in Epic tree
  • Disable Issue health status in Epic tree
• Multi-level child epics
• Start date and due date
  • From milestones
  • Inherited
• Roadmap in epics
• Reordering issues and child epics
• Moving issues and child epics between epics
• Updating epics
  • Using bulk editing
• Deleting an epic
• Closing and reopening epics
  • Using buttons
  • Using quick actions
• Navigating to an epic from an issue
• Promoting an issue to an epic
• Searching for an epic from epics list page
• Permissions
• Thread
• Comment or start a thread
• Award emoji
• Notifications

---

Proposed structure

https://docs.gitlab.com/ee/user/group/epics/index.html: this page gives an overview of WHAT an epic is and WHY it brings value.

• Use cases (enriched)
• Relationships between epics and issues
• Issue health status in Epic tree
  • Disable Issue health status in Epic tree
• Multi-level child epics

(new) https://docs.gitlab.com/ee/user/group/epics/parts_of_epic.html: this page describes the elements in the epic UI.

• Start date and due date
  • From milestones
  • Inherited
• Roadmap in epics
• Permissions
• Comment or start a thread
  • Thread
• Award emoji
• Notifications
• ... more sections for elements not yet covered

(new) https://docs.gitlab.com/ee/user/group/epics/manage_epics.html: this page describes what you can DO with an epic.

• Create an epic
• Add an issue to an epic
  • Add an existing issue to an epic
  • Create an issue from an epic
• Reorder issues and child epics
• Move issues and child epics between epics
• Update an epic
  • Using bulk editing
• Delete an epic
• Close and reopen epics
  • Using buttons
  • Using quick actions
• Open an epic from an issue
• Promote an issue to an epic
• Search for an epic from epics list page

Who can address the issue

@msedlakjakubowski, the technical writer assigned to Plan

Other links/references

&3270