Update documentation for consolidated Work items list

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Based on the epic context and the documentation issue template, here's a comprehensive description for the documentation issue:


Problem to solve

The consolidated "Work items" list is replacing the separate "Issues" and "Epics" menu items in GitLab. This represents a significant navigation and UX change that requires comprehensive documentation updates to help users understand and adopt the new unified interface.

Currently, documentation references the separate Issues and Epics listing pages. When the consolidated list becomes generally available (targeted for milestone 18.7, due 2025-12-12), users will need updated documentation that reflects:

  • The new unified "Work items" navigation structure
  • How to access and filter different work item types (Issues, Epics, Tasks, etc.) in a single view
  • Changes to URLs and routing (redirects from /issues and /epics to /work_items)
  • Updated screenshots and navigation paths throughout the docs

Further details

Epic context: &11918

Rollout status:

  • Feature flags: work_item_planning_view and work_items_consolidated_list_user
  • Currently enabled for GitLab team members on dev/staging
  • Targeted for GitLab.com rollout: 2025-12-01
  • Targeted for self-managed: 2025-12-12 (milestone 18.7)

Key changes requiring documentation:

  1. Navigation changes: "Issues" and "Epics" menu items → unified "Work items" menu item
  2. URL redirects: /issues/:iid and /epics/:iid/work_items/:iid
  3. Filtering: New Type filter with OR operator to view multiple work item types simultaneously
  4. Unified interface: Single page for viewing Issues, Epics, Tasks, and other work item types
  5. Settings and breadcrumbs: Updated to reference "work items" instead of separate issue/epic terminology

Proposal

When FF work_item_planning_view is enabled for GitLab.com and self-managed, update the following documentation areas:

1. Primary documentation page

  • Update: https://docs.gitlab.com/user/work_items/#view-all-work-items
  • Reflect that this is now the default view (not behind a feature flag)
  • Add comprehensive guidance on using the consolidated list
  • Document the Type filter and how to view specific work item types
  • Include updated screenshots showing the unified interface

2. Navigation and getting started guides

  • Update all references to "Issues list" or "Epics list" to mention the consolidated "Work items" view
  • Update navigation paths in tutorials and how-to guides
  • Add notes about URL redirects for users with bookmarked links

3. Work item type-specific documentation

  • Update Issues documentation to explain accessing issues through the Work items view
  • Update Epics documentation to explain accessing epics through the Work items view
  • Clarify that type-specific functionality remains available through filtering

4. Settings and permissions documentation

5. Screenshots and visual assets

  • Replace screenshots showing separate Issues/Epics navigation
  • Add new screenshots demonstrating the consolidated view
  • Update any diagrams showing navigation structure

6. Migration and transition guidance

  • Add a section explaining the change for existing users
  • Document how to find specific work item types in the new interface
  • Explain URL redirects and bookmark updates

Who can address the issue

Technical writers familiar with GitLab's work items feature and navigation structure. Coordination with the Product Planning group recommended for technical accuracy.

Other links/references

Related implementation issues:

Edited by Marcin Sedlak-Jakubowski