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
/issuesand/epicsto/work_items) - Updated screenshots and navigation paths throughout the docs
Further details
Epic context: &11918
Rollout status:
- Feature flags:
work_item_planning_viewandwork_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:
- Navigation changes: "Issues" and "Epics" menu items → unified "Work items" menu item
-
URL redirects:
/issues/:iidand/epics/:iid→/work_items/:iid - Filtering: New Type filter with OR operator to view multiple work item types simultaneously
- Unified interface: Single page for viewing Issues, Epics, Tasks, and other work item types
- 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
- Update references to "issue settings" to "work item settings" where applicable
- https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/project/settings/_index.md#L30
- https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/project/settings/_index.md#L104
- https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/integration/external-issue-tracker.md#L37
- 4x in https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/work_items/custom_fields.md
- This says Settings > Issues, which might be a mistake. I don't see it in my test (Free) group
- 5x in https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/work_items/status.md
- Document any changes to permissions or access controls
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
- Parent epic: &11918
- Documentation page to update: https://docs.gitlab.com/user/work_items/#view-all-work-items
- Related epic (Work Items - Listing pages): &11896
- Feedback issue: #579558
Related implementation issues:
- Redirect URLs: #579837 (closed)
- Navigation updates: #580271
- Type filter OR operator: #548480 (closed)