Skip to content

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

Edited by Marcin Sedlak-Jakubowski